Inicio
Pagos Presenciales
Tokenización
Aliados
Ambientes
Referencia API
Recursos
SDK Android
Integra pagos presenciales en tu aplicación Android
2
min read
2
2
min read
Incorpora las funcionalidades de pago presencial de OEL en aplicaciones Android mediante nuestro SDK para terminales SUNMI compatibles.
En esta guía encontrarás los componentes necesarios para preparar tu proyecto, incorporar las bibliotecas del SDK, inicializar el controlador de pagos, gestionar los eventos transaccionales y preparar tu integración para pruebas.
1. ¿Qué es el SDK Android de OEL?
El SDK Android de OEL proporciona las interfaces de software necesarias para integrar operaciones de pago presencial en aplicaciones que se ejecutan en dispositivos compatibles.
La integración permite que tu aplicación comercial invoque las operaciones disponibles, reciba notificaciones durante el proceso de pago y gestione los resultados devueltos por el SDK.
La versión SUNMI está compuesta por dos bibliotecas:
Biblioteca principal: contiene el núcleo del SDK, los modelos de solicitud y respuesta y las interfaces de control de transacciones.
Biblioteca específica de SUNMI: contiene los componentes de integración con el hardware y los servicios del dispositivo.
La disponibilidad de las operaciones depende de la versión del SDK, el modelo de terminal y la configuración del comercio.
Información de Versión
Propiedad | Valor |
|---|---|
Versión del SDK |
|
Plataforma | Android |
Fabricante objetivo | SUNMI |
Formato de distribución | Android Archive ( |
Paquete del controlador |
|
Importante: Utiliza siempre las bibliotecas oficiales correspondientes al dispositivo y a la versión autorizada para tu implementación.
2. Requisitos previos
Antes de comenzar, asegúrate de contar con:
Android Studio y un entorno de desarrollo Android configurado.
El SDK oficial correspondiente a SUNMI.
Un dispositivo compatible y habilitado para pruebas.
Credenciales de desarrollo del comercio.
Acceso al ambiente de pruebas.
La documentación técnica de la versión que vas a integrar.
El manifiesto de las bibliotecas requiere Android API 21 como nivel mínimo. Sin embargo, este dato no garantiza por sí solo la compatibilidad con todos los dispositivos o versiones del sistema operativo.
Confirma los requisitos definitivos para el modelo de terminal que utilizarás.
3. Incorporar el SDK al proyecto
Paso 1. Copia las bibliotecas
Crea la carpeta libs dentro del módulo de tu aplicación, si todavía no existe.
Copia los dos archivos AAR oficiales de la versión correspondiente:
olipaysdk-2025-08-19_10.47-v4.aarolipaysdk-sunmi-2025-08-19_10.47-v4.aar
La estructura quedará de la siguiente manera:
Paso 2. Declara las dependencias
En el archivo app/build.gradle.kts, agrega las siguientes dependencias dentro del bloque dependencies:
Después, sincroniza el proyecto con Gradle y verifica que las bibliotecas se resuelvan correctamente.
Nota: el SDK específico de SUNMI hace referencia a componentes del fabricante que no están incluidos dentro de los dos archivos AAR revisados. Si el entorno de compilación no resuelve esas clases, solicita al proveedor la dependencia oficial adicional que corresponda al dispositivo.
Paso 3. Verifica los permisos
Las bibliotecas incluyen declaraciones de permisos Android relacionados con las capacidades del dispositivo. Antes de liberar la aplicación:
Revisa el manifiesto combinado de tu proyecto.
Confirma cuáles permisos requiere realmente tu modelo de terminal.
Solicita permisos en tiempo de ejecución cuando corresponda.
Verifica con el proveedor los permisos que dependen de firmware, privilegios del fabricante o configuración del dispositivo.
No copies indiscriminadamente todos los permisos del proyecto de ejemplo: varios corresponden a funcionalidades específicas de su implementación.
4. Inicializar el SDK
La inicialización prepara el controlador de pagos y registra los eventos que utilizará la aplicación durante la integración.
El SDK SUNMI expone el controlador:
También utiliza las clases comunes QpAmbiente, QpLocale y QpayControlEventosImpl.
Ejemplo de inicialización en Kotlin
El siguiente fragmento muestra la estructura de inicialización verificada. Debe incorporarse dentro de una Activity y adaptarse al mecanismo autorizado de provisión de credenciales.
En este ejemplo, MainActivity representa el nombre de tu actividad. Sustitúyelo si utilizas otra clase.
El fragmento ilustra la inicialización y dos callbacks; no representa una implementación completa de pagos ni sustituye el tratamiento de errores que deberá incorporar la aplicación.
Parámetros de inicialización
Parámetro | Función |
|---|---|
| Contexto de la aplicación Android. |
| Identificador del comercio autorizado. |
| Credencial requerida por el SDK. |
| Selecciona el ambiente de pruebas. |
| Configura el idioma español. |
| Permite recibir eventos del controlador. |
El SDK también expone los ambientes PRODUCTION, VGS y VGS_LIVE, así como el idioma ENGLISH.
Utiliza únicamente el ambiente autorizado para tu integración.
5. Comprender los eventos del SDK
El SDK utiliza callbacks para informar sobre el estado de la integración, los resultados de las operaciones y los errores.
qpInicializado()
Se ejecuta cuando el controlador notifica que la inicialización ha finalizado correctamente.
Utiliza este evento para habilitar las funciones de pago de tu interfaz, una vez que se cumplan las demás condiciones operativas.
qpMostrarEstadoTexto(resultado, codigo)
Permite recibir mensajes de estado durante el proceso de pago, por ejemplo, instrucciones al usuario o información sobre el avance de la operación.
Utiliza estos eventos para actualizar la interfaz sin bloquear el hilo principal de Android.
qpRegresaTransaccion(resultado)
Entrega el resultado de una transacción mediante un mapa de datos.
Entre los campos observados en el proyecto de ejemplo se encuentran:
DescripcionCodigoNumeroTransaccionReferenciaBancoCodigoAprobacionMonto
La presencia y el significado definitivo de cada campo deben verificarse en el contrato de respuesta de la versión correspondiente.
qpError(...)
Permite recibir información relacionada con errores y situaciones que requieren atención.
La interfaz incluye datos como el mensaje, código de error, indicación para retirar la tarjeta, identificador de transacción, monto, código de aprobación y referencia bancaria.
No todos los errores significan lo mismo. Implementa un tratamiento específico para cada escenario documentado y no marques una venta como aprobada basándote únicamente en la ausencia de errores.
6. Ejecutar una operación de venta
El controlador expone el método qpRealizaTransaccion(...) para iniciar una operación de venta.
Su firma pública verificada es:
El método devuelve un identificador de transacción de tipo String y puede lanzar TransactionOngoingException cuando ya existe una operación en curso.
Antes de invocarlo, tu aplicación debe:
Validar el monto y los datos comerciales.
Confirmar que el SDK está inicializado.
Registrar el callback que recibirá el resultado.
Evitar iniciar una segunda operación mientras la anterior continúe activa.
Interpretar la respuesta conforme a las reglas oficiales.
Importante: los tres parámetros enteros finales aparecen en la API pública y en el proyecto de ejemplo, pero su significado no está documentado en los archivos revisados. No asignes valores arbitrarios ni publiques una llamada de venta como ejemplo definitivo hasta confirmar esos parámetros con la documentación oficial.
Excepciones relevantes
QpayControllerNotInitializedException: indica que se intentó utilizar el controlador sin una inicialización válida.TransactionOngoingException: indica que existe una operación en curso que debe resolverse antes de iniciar otra.
Cuando ocurra una excepción, conserva la trazabilidad del intento y aplica el procedimiento de recuperación correspondiente. No reintentes un cobro sin determinar el estado de la operación anterior.
7. Operaciones complementarias
Además de la venta, el SDK expone métodos relacionados con otras etapas del ciclo de vida de una transacción.
Método | Finalidad general |
|---|---|
| Solicitar una preautorización. |
| Completar una preautorización, según las reglas aplicables. |
| Solicitar una cancelación. |
| Solicitar una devolución. |
| Cancelar una preautorización, cuando corresponda. |
| Solicitar una reautorización. |
| Consultar información de historial. |
| Consultar información de una transacción. |
| Solicitar la impresión de un voucher. |
| Gestionar el envío de información del voucher. |
Las condiciones de uso, parámetros, callbacks y restricciones de cada operación deben consultarse en la referencia técnica correspondiente.
No todas las operaciones tienen necesariamente la misma disponibilidad para cada comercio o dispositivo.
8. Seguridad y manejo de credenciales
Las credenciales utilizadas para inicializar el SDK deben administrarse conforme a los procedimientos autorizados de Bloomin/OEL.
Recomendaciones:
No escribas credenciales reales directamente en el código fuente.
No incluyas contraseñas en mensajes de diagnóstico o registros de aplicación.
No publiques archivos de configuración con secretos.
Limita el acceso a las credenciales durante el desarrollo y la operación.
Considera que los valores incluidos en una aplicación móvil pueden llegar a extraerse del paquete compilado; la ofuscación no constituye una garantía de confidencialidad.
Utiliza el mecanismo de provisión y protección de credenciales aprobado para la solución.
No almacenes datos sensibles de tarjeta fuera de los mecanismos autorizados.
Mantén separadas las configuraciones de desarrollo y producción.
9. Pruebas de integración
Antes de pasar a producción, valida los escenarios correspondientes a las operaciones habilitadas.
El proyecto compila con las bibliotecas correctas para SUNMI.
El dispositivo y la versión de Android son compatibles.
La inicialización se completa correctamente.
La aplicación recibe los eventos de estado.
Se procesa una venta de prueba aprobada.
Se manejan las operaciones rechazadas.
Se contemplan los errores técnicos y de inicialización.
Se evita iniciar operaciones simultáneas no permitidas.
Se gestiona correctamente un resultado indeterminado.
Se valida el comportamiento de cancelaciones y devoluciones, cuando estén habilitadas.
Se revisan los permisos y requisitos del dispositivo.
No se exponen credenciales ni datos sensibles en los logs.
Los casos definitivos de certificación deben alinearse con los requisitos operativos de OEL.
10. Paso a producción
Antes de liberar la aplicación, confirma que:
La integración se ha validado en el ambiente de desarrollo.
El comercio y el dispositivo están habilitados.
Se han completado las pruebas y certificaciones requeridas.
Se ha configurado el ambiente productivo autorizado.
Existe un procedimiento para atender errores y operaciones pendientes.
La aplicación protege credenciales y datos sensibles.
No cambies al ambiente productivo únicamente por haber completado una venta de prueba. La liberación debe cumplir los requisitos aplicables a la solución.
Recursos relacionados
Terminales compatibles
Consulta los modelos y requisitos de los dispositivos soportados.
Ambiente de desarrollo
Revisa la configuración y las credenciales necesarias para realizar pruebas.
Integración SOAP con equipos propios
Consulta la alternativa para sistemas que consumen directamente los servicios SOAP de OpGateway.
Referencia técnica del SDK
Consulta las firmas de métodos, parámetros, eventos y estructuras de respuesta disponibles para la versión autorizada.
Incorpora las funcionalidades de pago presencial de OEL en aplicaciones Android mediante nuestro SDK para terminales SUNMI compatibles.
En esta guía encontrarás los componentes necesarios para preparar tu proyecto, incorporar las bibliotecas del SDK, inicializar el controlador de pagos, gestionar los eventos transaccionales y preparar tu integración para pruebas.
1. ¿Qué es el SDK Android de OEL?
El SDK Android de OEL proporciona las interfaces de software necesarias para integrar operaciones de pago presencial en aplicaciones que se ejecutan en dispositivos compatibles.
La integración permite que tu aplicación comercial invoque las operaciones disponibles, reciba notificaciones durante el proceso de pago y gestione los resultados devueltos por el SDK.
La versión SUNMI está compuesta por dos bibliotecas:
Biblioteca principal: contiene el núcleo del SDK, los modelos de solicitud y respuesta y las interfaces de control de transacciones.
Biblioteca específica de SUNMI: contiene los componentes de integración con el hardware y los servicios del dispositivo.
La disponibilidad de las operaciones depende de la versión del SDK, el modelo de terminal y la configuración del comercio.
Información de Versión
Propiedad | Valor |
|---|---|
Versión del SDK |
|
Plataforma | Android |
Fabricante objetivo | SUNMI |
Formato de distribución | Android Archive ( |
Paquete del controlador |
|
Importante: Utiliza siempre las bibliotecas oficiales correspondientes al dispositivo y a la versión autorizada para tu implementación.
2. Requisitos previos
Antes de comenzar, asegúrate de contar con:
Android Studio y un entorno de desarrollo Android configurado.
El SDK oficial correspondiente a SUNMI.
Un dispositivo compatible y habilitado para pruebas.
Credenciales de desarrollo del comercio.
Acceso al ambiente de pruebas.
La documentación técnica de la versión que vas a integrar.
El manifiesto de las bibliotecas requiere Android API 21 como nivel mínimo. Sin embargo, este dato no garantiza por sí solo la compatibilidad con todos los dispositivos o versiones del sistema operativo.
Confirma los requisitos definitivos para el modelo de terminal que utilizarás.
3. Incorporar el SDK al proyecto
Paso 1. Copia las bibliotecas
Crea la carpeta libs dentro del módulo de tu aplicación, si todavía no existe.
Copia los dos archivos AAR oficiales de la versión correspondiente:
olipaysdk-2025-08-19_10.47-v4.aarolipaysdk-sunmi-2025-08-19_10.47-v4.aar
La estructura quedará de la siguiente manera:
Paso 2. Declara las dependencias
En el archivo app/build.gradle.kts, agrega las siguientes dependencias dentro del bloque dependencies:
Después, sincroniza el proyecto con Gradle y verifica que las bibliotecas se resuelvan correctamente.
Nota: el SDK específico de SUNMI hace referencia a componentes del fabricante que no están incluidos dentro de los dos archivos AAR revisados. Si el entorno de compilación no resuelve esas clases, solicita al proveedor la dependencia oficial adicional que corresponda al dispositivo.
Paso 3. Verifica los permisos
Las bibliotecas incluyen declaraciones de permisos Android relacionados con las capacidades del dispositivo. Antes de liberar la aplicación:
Revisa el manifiesto combinado de tu proyecto.
Confirma cuáles permisos requiere realmente tu modelo de terminal.
Solicita permisos en tiempo de ejecución cuando corresponda.
Verifica con el proveedor los permisos que dependen de firmware, privilegios del fabricante o configuración del dispositivo.
No copies indiscriminadamente todos los permisos del proyecto de ejemplo: varios corresponden a funcionalidades específicas de su implementación.
4. Inicializar el SDK
La inicialización prepara el controlador de pagos y registra los eventos que utilizará la aplicación durante la integración.
El SDK SUNMI expone el controlador:
También utiliza las clases comunes QpAmbiente, QpLocale y QpayControlEventosImpl.
Ejemplo de inicialización en Kotlin
El siguiente fragmento muestra la estructura de inicialización verificada. Debe incorporarse dentro de una Activity y adaptarse al mecanismo autorizado de provisión de credenciales.
En este ejemplo, MainActivity representa el nombre de tu actividad. Sustitúyelo si utilizas otra clase.
El fragmento ilustra la inicialización y dos callbacks; no representa una implementación completa de pagos ni sustituye el tratamiento de errores que deberá incorporar la aplicación.
Parámetros de inicialización
Parámetro | Función |
|---|---|
| Contexto de la aplicación Android. |
| Identificador del comercio autorizado. |
| Credencial requerida por el SDK. |
| Selecciona el ambiente de pruebas. |
| Configura el idioma español. |
| Permite recibir eventos del controlador. |
El SDK también expone los ambientes PRODUCTION, VGS y VGS_LIVE, así como el idioma ENGLISH.
Utiliza únicamente el ambiente autorizado para tu integración.
5. Comprender los eventos del SDK
El SDK utiliza callbacks para informar sobre el estado de la integración, los resultados de las operaciones y los errores.
qpInicializado()
Se ejecuta cuando el controlador notifica que la inicialización ha finalizado correctamente.
Utiliza este evento para habilitar las funciones de pago de tu interfaz, una vez que se cumplan las demás condiciones operativas.
qpMostrarEstadoTexto(resultado, codigo)
Permite recibir mensajes de estado durante el proceso de pago, por ejemplo, instrucciones al usuario o información sobre el avance de la operación.
Utiliza estos eventos para actualizar la interfaz sin bloquear el hilo principal de Android.
qpRegresaTransaccion(resultado)
Entrega el resultado de una transacción mediante un mapa de datos.
Entre los campos observados en el proyecto de ejemplo se encuentran:
DescripcionCodigoNumeroTransaccionReferenciaBancoCodigoAprobacionMonto
La presencia y el significado definitivo de cada campo deben verificarse en el contrato de respuesta de la versión correspondiente.
qpError(...)
Permite recibir información relacionada con errores y situaciones que requieren atención.
La interfaz incluye datos como el mensaje, código de error, indicación para retirar la tarjeta, identificador de transacción, monto, código de aprobación y referencia bancaria.
No todos los errores significan lo mismo. Implementa un tratamiento específico para cada escenario documentado y no marques una venta como aprobada basándote únicamente en la ausencia de errores.
6. Ejecutar una operación de venta
El controlador expone el método qpRealizaTransaccion(...) para iniciar una operación de venta.
Su firma pública verificada es:
El método devuelve un identificador de transacción de tipo String y puede lanzar TransactionOngoingException cuando ya existe una operación en curso.
Antes de invocarlo, tu aplicación debe:
Validar el monto y los datos comerciales.
Confirmar que el SDK está inicializado.
Registrar el callback que recibirá el resultado.
Evitar iniciar una segunda operación mientras la anterior continúe activa.
Interpretar la respuesta conforme a las reglas oficiales.
Importante: los tres parámetros enteros finales aparecen en la API pública y en el proyecto de ejemplo, pero su significado no está documentado en los archivos revisados. No asignes valores arbitrarios ni publiques una llamada de venta como ejemplo definitivo hasta confirmar esos parámetros con la documentación oficial.
Excepciones relevantes
QpayControllerNotInitializedException: indica que se intentó utilizar el controlador sin una inicialización válida.TransactionOngoingException: indica que existe una operación en curso que debe resolverse antes de iniciar otra.
Cuando ocurra una excepción, conserva la trazabilidad del intento y aplica el procedimiento de recuperación correspondiente. No reintentes un cobro sin determinar el estado de la operación anterior.
7. Operaciones complementarias
Además de la venta, el SDK expone métodos relacionados con otras etapas del ciclo de vida de una transacción.
Método | Finalidad general |
|---|---|
| Solicitar una preautorización. |
| Completar una preautorización, según las reglas aplicables. |
| Solicitar una cancelación. |
| Solicitar una devolución. |
| Cancelar una preautorización, cuando corresponda. |
| Solicitar una reautorización. |
| Consultar información de historial. |
| Consultar información de una transacción. |
| Solicitar la impresión de un voucher. |
| Gestionar el envío de información del voucher. |
Las condiciones de uso, parámetros, callbacks y restricciones de cada operación deben consultarse en la referencia técnica correspondiente.
No todas las operaciones tienen necesariamente la misma disponibilidad para cada comercio o dispositivo.
8. Seguridad y manejo de credenciales
Las credenciales utilizadas para inicializar el SDK deben administrarse conforme a los procedimientos autorizados de Bloomin/OEL.
Recomendaciones:
No escribas credenciales reales directamente en el código fuente.
No incluyas contraseñas en mensajes de diagnóstico o registros de aplicación.
No publiques archivos de configuración con secretos.
Limita el acceso a las credenciales durante el desarrollo y la operación.
Considera que los valores incluidos en una aplicación móvil pueden llegar a extraerse del paquete compilado; la ofuscación no constituye una garantía de confidencialidad.
Utiliza el mecanismo de provisión y protección de credenciales aprobado para la solución.
No almacenes datos sensibles de tarjeta fuera de los mecanismos autorizados.
Mantén separadas las configuraciones de desarrollo y producción.
9. Pruebas de integración
Antes de pasar a producción, valida los escenarios correspondientes a las operaciones habilitadas.
El proyecto compila con las bibliotecas correctas para SUNMI.
El dispositivo y la versión de Android son compatibles.
La inicialización se completa correctamente.
La aplicación recibe los eventos de estado.
Se procesa una venta de prueba aprobada.
Se manejan las operaciones rechazadas.
Se contemplan los errores técnicos y de inicialización.
Se evita iniciar operaciones simultáneas no permitidas.
Se gestiona correctamente un resultado indeterminado.
Se valida el comportamiento de cancelaciones y devoluciones, cuando estén habilitadas.
Se revisan los permisos y requisitos del dispositivo.
No se exponen credenciales ni datos sensibles en los logs.
Los casos definitivos de certificación deben alinearse con los requisitos operativos de OEL.
10. Paso a producción
Antes de liberar la aplicación, confirma que:
La integración se ha validado en el ambiente de desarrollo.
El comercio y el dispositivo están habilitados.
Se han completado las pruebas y certificaciones requeridas.
Se ha configurado el ambiente productivo autorizado.
Existe un procedimiento para atender errores y operaciones pendientes.
La aplicación protege credenciales y datos sensibles.
No cambies al ambiente productivo únicamente por haber completado una venta de prueba. La liberación debe cumplir los requisitos aplicables a la solución.
Recursos relacionados
Terminales compatibles
Consulta los modelos y requisitos de los dispositivos soportados.
Ambiente de desarrollo
Revisa la configuración y las credenciales necesarias para realizar pruebas.
Integración SOAP con equipos propios
Consulta la alternativa para sistemas que consumen directamente los servicios SOAP de OpGateway.
Referencia técnica del SDK
Consulta las firmas de métodos, parámetros, eventos y estructuras de respuesta disponibles para la versión autorizada.
Incorpora las funcionalidades de pago presencial de OEL en aplicaciones Android mediante nuestro SDK para terminales SUNMI compatibles.
En esta guía encontrarás los componentes necesarios para preparar tu proyecto, incorporar las bibliotecas del SDK, inicializar el controlador de pagos, gestionar los eventos transaccionales y preparar tu integración para pruebas.
1. ¿Qué es el SDK Android de OEL?
El SDK Android de OEL proporciona las interfaces de software necesarias para integrar operaciones de pago presencial en aplicaciones que se ejecutan en dispositivos compatibles.
La integración permite que tu aplicación comercial invoque las operaciones disponibles, reciba notificaciones durante el proceso de pago y gestione los resultados devueltos por el SDK.
La versión SUNMI está compuesta por dos bibliotecas:
Biblioteca principal: contiene el núcleo del SDK, los modelos de solicitud y respuesta y las interfaces de control de transacciones.
Biblioteca específica de SUNMI: contiene los componentes de integración con el hardware y los servicios del dispositivo.
La disponibilidad de las operaciones depende de la versión del SDK, el modelo de terminal y la configuración del comercio.
Información de Versión
Propiedad | Valor |
|---|---|
Versión del SDK |
|
Plataforma | Android |
Fabricante objetivo | SUNMI |
Formato de distribución | Android Archive ( |
Paquete del controlador |
|
Importante: Utiliza siempre las bibliotecas oficiales correspondientes al dispositivo y a la versión autorizada para tu implementación.
2. Requisitos previos
Antes de comenzar, asegúrate de contar con:
Android Studio y un entorno de desarrollo Android configurado.
El SDK oficial correspondiente a SUNMI.
Un dispositivo compatible y habilitado para pruebas.
Credenciales de desarrollo del comercio.
Acceso al ambiente de pruebas.
La documentación técnica de la versión que vas a integrar.
El manifiesto de las bibliotecas requiere Android API 21 como nivel mínimo. Sin embargo, este dato no garantiza por sí solo la compatibilidad con todos los dispositivos o versiones del sistema operativo.
Confirma los requisitos definitivos para el modelo de terminal que utilizarás.
3. Incorporar el SDK al proyecto
Paso 1. Copia las bibliotecas
Crea la carpeta libs dentro del módulo de tu aplicación, si todavía no existe.
Copia los dos archivos AAR oficiales de la versión correspondiente:
olipaysdk-2025-08-19_10.47-v4.aarolipaysdk-sunmi-2025-08-19_10.47-v4.aar
La estructura quedará de la siguiente manera:
Paso 2. Declara las dependencias
En el archivo app/build.gradle.kts, agrega las siguientes dependencias dentro del bloque dependencies:
Después, sincroniza el proyecto con Gradle y verifica que las bibliotecas se resuelvan correctamente.
Nota: el SDK específico de SUNMI hace referencia a componentes del fabricante que no están incluidos dentro de los dos archivos AAR revisados. Si el entorno de compilación no resuelve esas clases, solicita al proveedor la dependencia oficial adicional que corresponda al dispositivo.
Paso 3. Verifica los permisos
Las bibliotecas incluyen declaraciones de permisos Android relacionados con las capacidades del dispositivo. Antes de liberar la aplicación:
Revisa el manifiesto combinado de tu proyecto.
Confirma cuáles permisos requiere realmente tu modelo de terminal.
Solicita permisos en tiempo de ejecución cuando corresponda.
Verifica con el proveedor los permisos que dependen de firmware, privilegios del fabricante o configuración del dispositivo.
No copies indiscriminadamente todos los permisos del proyecto de ejemplo: varios corresponden a funcionalidades específicas de su implementación.
4. Inicializar el SDK
La inicialización prepara el controlador de pagos y registra los eventos que utilizará la aplicación durante la integración.
El SDK SUNMI expone el controlador:
También utiliza las clases comunes QpAmbiente, QpLocale y QpayControlEventosImpl.
Ejemplo de inicialización en Kotlin
El siguiente fragmento muestra la estructura de inicialización verificada. Debe incorporarse dentro de una Activity y adaptarse al mecanismo autorizado de provisión de credenciales.
En este ejemplo, MainActivity representa el nombre de tu actividad. Sustitúyelo si utilizas otra clase.
El fragmento ilustra la inicialización y dos callbacks; no representa una implementación completa de pagos ni sustituye el tratamiento de errores que deberá incorporar la aplicación.
Parámetros de inicialización
Parámetro | Función |
|---|---|
| Contexto de la aplicación Android. |
| Identificador del comercio autorizado. |
| Credencial requerida por el SDK. |
| Selecciona el ambiente de pruebas. |
| Configura el idioma español. |
| Permite recibir eventos del controlador. |
El SDK también expone los ambientes PRODUCTION, VGS y VGS_LIVE, así como el idioma ENGLISH.
Utiliza únicamente el ambiente autorizado para tu integración.
5. Comprender los eventos del SDK
El SDK utiliza callbacks para informar sobre el estado de la integración, los resultados de las operaciones y los errores.
qpInicializado()
Se ejecuta cuando el controlador notifica que la inicialización ha finalizado correctamente.
Utiliza este evento para habilitar las funciones de pago de tu interfaz, una vez que se cumplan las demás condiciones operativas.
qpMostrarEstadoTexto(resultado, codigo)
Permite recibir mensajes de estado durante el proceso de pago, por ejemplo, instrucciones al usuario o información sobre el avance de la operación.
Utiliza estos eventos para actualizar la interfaz sin bloquear el hilo principal de Android.
qpRegresaTransaccion(resultado)
Entrega el resultado de una transacción mediante un mapa de datos.
Entre los campos observados en el proyecto de ejemplo se encuentran:
DescripcionCodigoNumeroTransaccionReferenciaBancoCodigoAprobacionMonto
La presencia y el significado definitivo de cada campo deben verificarse en el contrato de respuesta de la versión correspondiente.
qpError(...)
Permite recibir información relacionada con errores y situaciones que requieren atención.
La interfaz incluye datos como el mensaje, código de error, indicación para retirar la tarjeta, identificador de transacción, monto, código de aprobación y referencia bancaria.
No todos los errores significan lo mismo. Implementa un tratamiento específico para cada escenario documentado y no marques una venta como aprobada basándote únicamente en la ausencia de errores.
6. Ejecutar una operación de venta
El controlador expone el método qpRealizaTransaccion(...) para iniciar una operación de venta.
Su firma pública verificada es:
El método devuelve un identificador de transacción de tipo String y puede lanzar TransactionOngoingException cuando ya existe una operación en curso.
Antes de invocarlo, tu aplicación debe:
Validar el monto y los datos comerciales.
Confirmar que el SDK está inicializado.
Registrar el callback que recibirá el resultado.
Evitar iniciar una segunda operación mientras la anterior continúe activa.
Interpretar la respuesta conforme a las reglas oficiales.
Importante: los tres parámetros enteros finales aparecen en la API pública y en el proyecto de ejemplo, pero su significado no está documentado en los archivos revisados. No asignes valores arbitrarios ni publiques una llamada de venta como ejemplo definitivo hasta confirmar esos parámetros con la documentación oficial.
Excepciones relevantes
QpayControllerNotInitializedException: indica que se intentó utilizar el controlador sin una inicialización válida.TransactionOngoingException: indica que existe una operación en curso que debe resolverse antes de iniciar otra.
Cuando ocurra una excepción, conserva la trazabilidad del intento y aplica el procedimiento de recuperación correspondiente. No reintentes un cobro sin determinar el estado de la operación anterior.
7. Operaciones complementarias
Además de la venta, el SDK expone métodos relacionados con otras etapas del ciclo de vida de una transacción.
Método | Finalidad general |
|---|---|
| Solicitar una preautorización. |
| Completar una preautorización, según las reglas aplicables. |
| Solicitar una cancelación. |
| Solicitar una devolución. |
| Cancelar una preautorización, cuando corresponda. |
| Solicitar una reautorización. |
| Consultar información de historial. |
| Consultar información de una transacción. |
| Solicitar la impresión de un voucher. |
| Gestionar el envío de información del voucher. |
Las condiciones de uso, parámetros, callbacks y restricciones de cada operación deben consultarse en la referencia técnica correspondiente.
No todas las operaciones tienen necesariamente la misma disponibilidad para cada comercio o dispositivo.
8. Seguridad y manejo de credenciales
Las credenciales utilizadas para inicializar el SDK deben administrarse conforme a los procedimientos autorizados de Bloomin/OEL.
Recomendaciones:
No escribas credenciales reales directamente en el código fuente.
No incluyas contraseñas en mensajes de diagnóstico o registros de aplicación.
No publiques archivos de configuración con secretos.
Limita el acceso a las credenciales durante el desarrollo y la operación.
Considera que los valores incluidos en una aplicación móvil pueden llegar a extraerse del paquete compilado; la ofuscación no constituye una garantía de confidencialidad.
Utiliza el mecanismo de provisión y protección de credenciales aprobado para la solución.
No almacenes datos sensibles de tarjeta fuera de los mecanismos autorizados.
Mantén separadas las configuraciones de desarrollo y producción.
9. Pruebas de integración
Antes de pasar a producción, valida los escenarios correspondientes a las operaciones habilitadas.
El proyecto compila con las bibliotecas correctas para SUNMI.
El dispositivo y la versión de Android son compatibles.
La inicialización se completa correctamente.
La aplicación recibe los eventos de estado.
Se procesa una venta de prueba aprobada.
Se manejan las operaciones rechazadas.
Se contemplan los errores técnicos y de inicialización.
Se evita iniciar operaciones simultáneas no permitidas.
Se gestiona correctamente un resultado indeterminado.
Se valida el comportamiento de cancelaciones y devoluciones, cuando estén habilitadas.
Se revisan los permisos y requisitos del dispositivo.
No se exponen credenciales ni datos sensibles en los logs.
Los casos definitivos de certificación deben alinearse con los requisitos operativos de OEL.
10. Paso a producción
Antes de liberar la aplicación, confirma que:
La integración se ha validado en el ambiente de desarrollo.
El comercio y el dispositivo están habilitados.
Se han completado las pruebas y certificaciones requeridas.
Se ha configurado el ambiente productivo autorizado.
Existe un procedimiento para atender errores y operaciones pendientes.
La aplicación protege credenciales y datos sensibles.
No cambies al ambiente productivo únicamente por haber completado una venta de prueba. La liberación debe cumplir los requisitos aplicables a la solución.
Recursos relacionados
Terminales compatibles
Consulta los modelos y requisitos de los dispositivos soportados.
Ambiente de desarrollo
Revisa la configuración y las credenciales necesarias para realizar pruebas.
Integración SOAP con equipos propios
Consulta la alternativa para sistemas que consumen directamente los servicios SOAP de OpGateway.
Referencia técnica del SDK
Consulta las firmas de métodos, parámetros, eventos y estructuras de respuesta disponibles para la versión autorizada.
¿Listo para integrar?
Comienza en ambiente de desarrollo, valida tus primeras operaciones y prepara tu integración para certificación. Cuando el flujo este completo, podrás solicitar el paso a produccion.
¿Listo para integrar?
Comienza en ambiente de desarrollo, valida tus primeras operaciones y prepara tu integración para certificación. Cuando el flujo este completo, podrás solicitar el paso a produccion.
© 2026 Derechos Reservados
© 2026 Derechos Reservados