nexi_payment
Un plugin de Flutter para las pasarelas de pago de Nexi: el checkout de Nexi en Android e iOS, y un resultado en el que la app puede confiar.
- Rol
- Autor y mantenedor: la API de Dart, el código de Android (Java) e iOS (Swift), las pruebas, la CI y las versiones
- Tipo
- Plugin de Flutter de código abierto, licencia MIT, en pub.dev
- Periodo
- 2020 – actualidad (2.3.0, julio de 2026)
- Plataformas
- Android e iOS
El producto
nexi_payment permite a una app Flutter cobrar a través de Nexi. La app entrega el pedido, el propio checkout de Nexi recoge la tarjeta (la app nunca la ve) y la app recibe lo que ocurrió: pagado, cancelado, o fallido y por qué.
Lo escribí en junio de 2020, mientras integraba Nexi en la app de Criluma Viaggi, y lo publiqué en pub.dev. En julio de 2026 lo reescribí como 2.0: la pasarela NPG, más reciente, junto a la clásica XPay, un único contrato de errores en las dos plataformas, pruebas que manejan los SDK reales y correcciones para los momentos en que los SDK nativos de Nexi se quedan en silencio o informan de algo equivocado.
- 7
- versiones estables en pub.dev, de la 1.0.0 en junio de 2020 a la 2.3.0 en julio de 2026
- 53
- de los 58 commits son míos; los demás llegaron como pull requests de colaboradores
- 2
- pasarelas de Nexi tras una única API de Dart: la clásica XPay y NPG
- 49
- pruebas automatizadas: 35 pruebas unitarias y 14 pruebas de integración que se ejecutan en un dispositivo
Recorrido
La app en acción
Elige una grabación o salta directamente a un capítulo.
Grabado en un emulador de Android a partir de una compilación de producción de la app de ejemplo, pagando en el sandbox público de Nexi. Los campos del checkout se localizan a través de DevTools y se tocan como lo haría un dedo; la página del sandbox necesita dos pequeños arreglos para funcionar, aplicados de la misma manera.
Qué hace
De un botón en la app a un resultado en el que puede confiar
01
Una sola llamada abre el checkout de Nexi
La app pasa el pedido (id, importe, moneda, idioma) y el plugin abre la Hosted Payment Page de Nexi a través del SDK nativo: una tarjeta o cualquiera de los otros métodos que ofrece Nexi. La tarjeta se escribe en la página de Nexi, nunca en la app.
02
Resumen y 3-D Secure
Nexi muestra el resumen con la tarjeta enmascarada y después pasa el control al banco del titular para 3-D Secure: en el sandbox, DemoBank, al que se le puede indicar que apruebe o que falle.
03
Un resultado en el que la app puede confiar
Los SDK nativos llaman a su callback «completed» para cualquier pago que haya terminado, incluidos los rechazados. El plugin solo informa de éxito para una operación final EXECUTED o AUTHORIZED; una autenticación fallida vuelve como fallo con el código de Nexi. Antes de la 2.0, iOS llegaba a devolver un pago denegado como una simple cadena de texto; ahora las dos plataformas lanzan los mismos errores con código.
04
Cualquier salida cierra la llamada
El botón Atrás, el propio enlace de cancelar de Nexi, una hoja descartada arrastrándola en iOS: cada uno resuelve el pago como cancelado, y el siguiente pago se abre con normalidad. Dos de esas salidas dejaban antes la app esperando una respuesta que nunca llegaba.
Por dentro
Cómo se construyó
Cubrir los silencios de los SDK
XPaySDK cierra su checkout con el botón Atrás de Android sin devolver la llamada, y NPGSDK en iOS puede dejar que su hoja se cierre sin avisar. El plugin vigila el ciclo de vida del checkout y resuelve con una cancelación cuando desaparece sin haber dicho nada (un resultado real siempre tiene prioridad), y una protección rechaza un segundo pago mientras haya uno abierto, en lugar de dejar dos llamadas pendientes.
Cuando el SDK no sabe leer su propia respuesta
NPGSDK 1.1.0 declara el additionalData de una operación como un mapa de cadenas, pero el backend anida un objeto dentro, así que en Android el SDK puede no conseguir interpretar el resultado de un pago que sí se completó. En ese caso el plugin vuelve a leer el pedido desde la API de pedidos de NPG e informa de lo que pasó realmente: nunca se inventa un éxito, y dice «resultado desconocido» cuando no puede saberlo.
Empaquetado, pruebas y versiones
Nexi no publica artefactos Maven y su pod de iOS no tiene slice para el simulador: los SDK de Android van dentro del plugin, y los frameworks de iOS se descargan de los repositorios de versiones de Nexi durante el pod install y se verifican contra checksums SHA-256 fijados. Las pruebas unitarias fijan el contrato del canal, las pruebas con Patrol manejan los SDK reales contra el sandbox de Nexi, la CI analiza, prueba y compila en cada push y pull request, y una etiqueta de versión publica en pub.dev.
Grabar un plugin de pagos
Un checkout real, en el sandbox de Nexi.
Un plugin no tiene pantallas propias, así que las grabaciones muestran su app de ejemplo, una compilación de producción en un emulador de Android, pagando de verdad en el sandbox público de Nexi.
- 1
El código publicado, compilado para producción
El repositorio en la etiqueta 2.3.0, la app de ejemplo compilada en modo release con las credenciales de sandbox que publica Nexi, instalada en un emulador. Sin claves privadas: los botones de la XPay clásica necesitan un terminal de pruebas propio del comercio y no se muestran.
- 2
Dentro de la página de Nexi a través de DevTools
El checkout es una página web dentro del WebView del SDK. El script de grabación encuentra sus campos a través de Chrome DevTools, que también indica dónde está el WebView en la pantalla, y los toca en la pantalla táctil del emulador como un dedo, escribiendo la tarjeta de prueba de Nexi.
- 3
Dos rarezas del sandbox
La página del sandbox a veces deja su botón de tarjeta sin etiqueta, y nunca habilita su botón de pagar para una tarjeta escrita a mano. El script corrige ambas cosas desde DevTools, la segunda exactamente como lo hace la propia guía de pruebas en dispositivo del plugin.
- 4
Tres desenlaces
Un pago que se completa, uno cuyo 3-D Secure falla y dos formas de marcharse. Cada toma empieza con la app limpia y un pedido nuevo.
Las páginas de pago, el comercio del sandbox (WWW.CHARTA.IT) y DemoBank pertenecen al sandbox público de Nexi. La tarjeta es la tarjeta de prueba que publica Nexi; el titular es inventado.
Aquí no hay nada que probar: el plugin funciona dentro de apps de Android e iOS. Está en pub.dev y GitHub.
Todas las pantallas
La colección completa de capturas
La app de ejemploLas dos pasarelas, el guardado de tarjetas y un cargo recurrente, con un botón para cada uno. Hosted Payment PageLa página de Nexi, abierta por el SDK nativo: tarjeta u otro método. La tarjetaLa tarjeta de prueba que publica Nexi; la app nunca ve el número. ResumenComercio, importe, pedido y la tarjeta enmascarada. 3-D SecureEl DemoBank del sandbox pide al titular de la tarjeta que confirme. EjecutadoEl plugin solo informa de éxito para un pago ejecutado o autorizado. FallidoTHREEDS_FAILED, no un éxito: el plugin comprueba la operación final. CanceladoBotón Atrás: el plugin convierte el silencio del SDK en una cancelación. Salir de la páginaLa cancelación propia de Nexi pide confirmación.
Siguiente caso de estudio
Referi →