Buenas prácticas para integrar un sistema de pagos en una app

Viernes, nueve de la noche. Una app de pedidos a domicilio en Guadalajara recibe su pico de la semana y el tablero de errores se pinta de rojo: el proveedor de pagos responde con demora, los reintentos se amontonan y tres clientes ven el cargo duplicado antes de que alguien abra la laptop. El código que procesaba el pago tenía ocho líneas. El que faltaba para evitar esto, bastantes más.

La escena es hipotética y el patrón, conocido. Según el Sistema de Información Económica del Banco de México, el SPEI procesó 7,410 millones de operaciones en 2025, contra 5,418 millones el año anterior. Y las estadísticas de comercio electrónico de la CONDUSEF cuentan 2,288 millones de solicitudes de compra con tarjeta enviadas a autorización ese mismo año, con 71 % aprobadas. Casi tres de cada diez intentos terminan en un rechazo que tu app tiene que saber mostrar.

Esta lista va de las decisiones previas al código a las que se resuelven en la implementación. Las primeras son difíciles de revertir; las últimas se corrigen en un sprint.

1. Decidir qué parte del flujo vive en tu servidor

En una app pequeña, la tentación es llamar al proveedor directo desde el celular. Funciona hasta que alguien descompila el APK y encuentra la llave privada. La app solo captura y tokeniza; la creación del cargo, la confirmación y cualquier operación que mueva dinero se hace desde tu backend, con credenciales que nunca viajan al dispositivo.

2. Tratar los datos de pago como datos personales

La nueva Ley Federal de Protección de Datos Personales en Posesión de los Particulares, publicada en el Diario Oficial de la Federación el 20 de marzo de 2025, obliga en su artículo 18 a mantener medidas de seguridad administrativas, técnicas y físicas y, en el 19, a informar de inmediato al titular cuando una vulneración afecte de forma significativa sus derechos patrimoniales. Un número de tarjeta en texto plano en tu base cae de lleno ahí. Guardar solo el token del proveedor y los últimos cuatro dígitos resuelve buena parte del problema.

3. Diseñar los estados del pago antes que las pantallas

Un pago pasa por pendiente, autorizado, capturado, rechazado, en revisión, reembolsado parcial, contracargado. Si tu modelo de datos solo contempla pagado y no pagado, cada caso intermedio termina en un ticket de soporte. Dibuja la máquina de estados completa y acuerda qué ve el usuario en cada una.

4. Hacer que cada operación sea idempotente

Una clave de idempotencia por intento evita la escena del inicio. Si la red se cae y el cliente reintenta, el servidor devuelve el resultado ya procesado en vez de crear un cargo nuevo. Casi todos los proveedores lo soportan. Que tu código lo use es otra cosa.

5. Clasificar los errores de la API antes de mostrarlos

Un rechazo trae código, mensaje y casi siempre una causa: fondos insuficientes, tarjeta vencida, límite del emisor, sospecha de fraude, timeout del proveedor. Un genérico «ocurrió un error» desperdicia esa información y empuja a reintentar a ciegas. Lo razonable es mapear cada código a un mensaje accionable, separar errores recuperables de definitivos y registrar el resto en logs. Los errores también pueden venir del equipo: quien cobra con terminal física puede revisar cómo cargar la batería de Point Pro 3 de forma correcta y prolongar su vida útil, un detalle que evita cortes en plena venta; la lógica de clasificar fallos aplica igual a cualquier dispositivo.

6. Confirmar el pago desde el webhook

Si tu sistema solo marca la orden como pagada cuando carga la pantalla de éxito, la venta del usuario que cerró la app un segundo antes queda en el limbo. La fuente de verdad tiene que ser la notificación que el proveedor manda a tu servidor, con validación de firma y tolerancia a duplicados y desorden. Si el comercio cobra en varias terminales, la fuente de verdad también debe ser una sola, y hay una guía de cómo configurar varias terminales Point en un mismo negocio paso a paso que ayuda a pensar cómo se concilian los pagos de cada dispositivo.

7. Prepararse para el contracargo desde el día uno

Las mismas estadísticas de la CONDUSEF registran 5.47 millones de contracargos en compras en línea durante 2025, el 0.34 % de las autorizadas. Parece poco hasta que lo multiplicas por tu ticket promedio. Guardar evidencia de cada transacción (IP, dispositivo, hora, comprobante de entrega) es lo que permite disputar. Ese año la comisión también atendió 8,093 reclamaciones por consumos vía internet no reconocidos, con 49.3 % de resolución favorable y 19 días de respuesta en promedio. Si tu app no ofrece una vía más rápida, el reclamo llega por fuera.

8. Probar los caminos feos en sandbox

Las tarjetas de prueba del sandbox fuerzan rechazos, pendientes y reembolsos; probar solo el pago aprobado es probar la mitad. Un plan mínimo recorre aprobado, rechazo por fondos y por fraude, pendiente que luego se aprueba, webhook duplicado y reembolso parcial.

9. Pensar la integración como algo que va a cambiar

Publicada en el DOF el 9 de marzo de 2018, la Ley para Regular las Instituciones de Tecnología Financiera obliga en su artículo 76 a entidades financieras, fintechs y cámaras de compensación a exponer interfaces de programación estandarizadas, y precisa que los datos transaccionales de un cliente solo se comparten con su autorización expresa. El mapa de APIs en México está regulado y se mueve. Encapsular al proveedor detrás de una capa propia permite cambiarlo o sumar otro sin reescribir la app.

Nada de esto es exótico; es la misma disciplina que aplicas a autenticación o sincronización, llevada al único módulo donde un bug se traduce directo en dinero ajeno. Queda abierta otra pregunta. Cuando el proveedor cambie su API, sus comisiones o su política de reembolsos, ¿cuánto de tu app va a tener que cambiar con él?