Integrar el botón de pago Yappy por API: qué va en el backend de tu comercio

Vendes en línea en Panamá y quieres cobrar con Yappy, porque es lo que la gente tiene en el teléfono. Buscas cómo poner el botón y te encuentras con dos cosas: que el botón que todo el mundo recuerda ya no existe, y que la ruta nueva es una integración por APIs.

Si tu tienda está en Shopify, Wix o WooCommerce, lo honesto es decirlo de entrada: no necesitas un desarrollo, necesitas la integración de Tilopay, que es la alianza oficial de Yappy para esas plataformas. Este post es para el otro caso, el de un sistema propio: una tienda a la medida, un portal de servicios, un sistema con cobros recurrentes o cobros parciales. Ahí sí hay que programar, y lo que sigue es cómo se arma.

Lo primero: la versión vieja ya no cobra

Yappy descontinuó la versión legacy del botón de pago el 31 de diciembre de 2025. Como extensión, siguió recibiendo pagos hasta el 30 de abril de 2026, sin soporte técnico, y a partir de esa fecha dejó de procesar pagos para los comercios que no migraron. El cambio se comunicó desde marzo de 2025.

¿Cómo sabes si estabas en esa versión? Según el aviso de Yappy, es probable que sí si al presionar "Pagar con Yappy" el cliente salía redirigido a un sitio que empieza por pagosbg.bgeneral.com, o si el botón no se ha actualizado en los últimos doce meses.

Dicho de otro modo: si todavía tienes ese botón puesto, no tienes un pendiente técnico, tienes ventas que no se están cobrando.

La ruta oficial para desarrollo propio son las APIs, con documentación y ejemplos en PHP, Node.js y .NET. Hay paquetes de la comunidad para algunos frameworks, pero conviene mirarlos con calma: el más reciente que encontramos para Laravel tiene trece instalaciones, una sola versión publicada y se inspira en un paquete anterior que está deprecado. Para algo que cobra dinero, eso es poco respaldo.

Las piezas

La integración tiene tres partes, y conviene tenerlas claras antes de escribir código:

1. Un botón que se carga desde el CDN de Yappy. No se dibuja a mano: es un componente web que Yappy sirve y que dispara eventos de JavaScript.
2. Dos endpoints tuyos en el backend. Uno que crea la orden cuando el cliente pulsa el botón, y otro que recibe la notificación de pago.
3. Las credenciales, que se generan en la web de Yappy Comercial: un ID de comercio y una clave secreta, atados al dominio del sitio que registras.

Un detalle operativo que vale su propio recordatorio: si regeneras las credenciales en Yappy Comercial, no se actualizan solas en tu configuración. Hay que copiarlas a mano. Es una causa de caída de cobros perfectamente evitable y pasa más de lo que parece.

Los dos POST van en el backend

La integración necesita dos llamadas HTTP de tipo POST:

• Validar el comercio. Se manda el ID de comercio y el dominio configurado, y devuelve un token de sesión.
• Crear la orden. Con ese token en la cabecera de autorización se manda el ID de comercio, el identificador de la orden, el dominio, la fecha, el alias del cliente, la URL donde quieres recibir la notificación y los montos (subtotal, impuestos, descuento y total).

La documentación de Yappy es explícita en algo que es la decisión más importante de toda la integración: estas llamadas se hacen desde tu backend. No desde el navegador.

La razón es simple. La clave secreta es lo que prueba que las órdenes las crea tu comercio. Si vive en el JavaScript de la página, cualquiera que abra el inspector puede crear órdenes a tu nombre. Hay ambientes separados para pruebas y producción, con URL distintas, y el alias que se usa en pruebas tiene que ser un teléfono registrado en el programa de pruebas de la app.

El frontend solo orquesta

El botón dispara un evento al pulsarse; ahí llamas a tu endpoint, que a su vez hace las dos llamadas a Yappy y le devuelve al botón el resultado de la creación de la orden. Después, el botón emite eventos de éxito o de error, y uno con los datos de la transacción.

Hay un evento que casi nadie implementa y que mejora mucho la experiencia: el que indica si el canal de Yappy está disponible. Con eso puedes explicarle al cliente por qué no puede pagar en este momento, en lugar de mostrarle un botón que no va a responder. También hay una propiedad para dejar el botón en estado de carga mientras tu backend trabaja.

El IPN es la fuente de verdad

Esta es la parte donde se pierde dinero.

El evento de éxito del navegador significa "al cliente le fue bien en la pantalla". La confirmación real llega por el IPN: una notificación que Yappy hace a un endpoint de tipo GET que tú expones y que registraste al crear la orden. Llega con el identificador de la orden, un hash, el estado y el dominio.

Dos reglas que no son negociables:

Marca el pedido como pagado solo con el IPN. Si lo marcas con el evento del frontend, basta con que el cliente cierre la pantalla en el momento equivocado, o que alguien recargue a mano, para que despaches un pedido que nadie pagó.

Valida el hash. Ese endpoint está abierto a internet. Si no compruebas el hash con tu clave secreta, cualquiera puede llamarlo con el número de un pedido y marcarlo como pagado. La forma exacta de calcularlo está en la documentación oficial, con ejemplos.

Y como una notificación puede llegar más de una vez, el receptor tiene que ser idempotente: procesar dos veces la misma notificación no puede despachar dos veces el pedido ni duplicar el asiento contable.

Cuatro estados, no dos

El IPN trae el estado de la orden, y son cuatro:

• Ejecutado: el cliente confirmó el pago y la compra se completó.
• Rechazado: el cliente no confirmó dentro de los cinco minutos que dura la vigencia del pedido.
• Cancelado: el cliente entró al proceso y lo canceló en la app.
• Expirado: el cliente nunca empezó el proceso y la solicitud venció.

Guardarlos por separado no es burocracia: es la única forma de entender dónde se te cae la conversión. "Expirado" te dice que el cliente ni abrió la app; "cancelado" te dice que la abrió y se arrepintió. Son dos problemas distintos de negocio.

Esos cinco minutos también condicionan el carrito. Si reservas inventario al crear la orden, tienes que liberarlo cuando la orden se rechaza, y permitir un reintento que no genere un pedido duplicado.

Dos límites que obligan a decidir

El identificador de la orden admite entre 1 y 15 caracteres. Parece un detalle y no lo es: el id interno de muchos sistemas no cabe, así que hay que decidir qué referencia se manda y cómo se relaciona con el pedido real. Los montos van con dos decimales y el total tiene un mínimo.

Además, hay un error específico para cuando el pedido ya fue registrado. Eso es un regalo: te obliga a pensar desde el principio qué pasa si el cliente pulsa el botón dos veces, que es lo que hace todo el mundo cuando algo tarda.

Después del cobro viene la factura

Cobrar no es facturar. El pedido pagado tiene que convertirse en un comprobante válido, y en Panamá eso pasa por el sistema de facturación electrónica. Si estás armando el cobro, conviene diseñar las dos cosas juntas: qué referencia une el pago con la factura y qué pasa si el pago entra y la facturación falla.

El detalle de cómo diseñamos este tipo de servicios lo escribimos en ventajas de crear APIs REST personalizadas, y la parte de infraestructura en migración a la nube.

Un escenario típico, para aterrizarlo: una empresa de servicios cobra mensualidades y antes mandaba un enlace de pago a mano. Ahora su sistema crea la orden cuando el cliente entra a su portal, recibe el IPN, marca la mensualidad como pagada solo con esa notificación y deja registrado el estado de cada intento. Lo que cambió no es el botón: es que el cobro quedó dentro del sistema, con registro de qué pasó en cada paso.

Checklist antes de salir a producción

1. ¿La clave secreta está solo en el servidor?
2. ¿Los dos POST se hacen desde el backend?
3. ¿El pedido se marca pagado solo con el IPN?
4. ¿Validas el hash de cada notificación?
5. ¿El receptor del IPN es idempotente?
6. ¿Guardas los cuatro estados por separado?
7. ¿Qué pasa con el inventario reservado cuando la orden se rechaza?
8. ¿El identificador de la orden cabe en quince caracteres y se puede rastrear?
9. ¿Usas el indicador de disponibilidad para no mostrar un botón muerto?
10. ¿Probaste en el ambiente de pruebas, con un número registrado, antes de tocar producción?

Errores comunes

• La clave secreta en el frontend. Es el error más grave y el más fácil de cometer.
• Confiar en el evento del navegador para dar el pedido por pagado.
• No validar el hash del IPN, dejando un endpoint abierto que marca pedidos como pagados.
• No manejar expirado ni cancelado, y quedarse con pedidos colgados que nadie revisa.
• Un identificador de orden que no cabe o que no se puede relacionar con el pedido real.
• No reconciliar. Alguien tiene que comparar lo cobrado con lo registrado, al menos al cierre.
• Probar contra producción porque el ambiente de pruebas da pereza configurar.
• Olvidar que las credenciales regeneradas no se actualizan solas.

Si te toca hacerlo

Si el cobro vive dentro de un sistema propio y necesitas que Yappy quede bien integrado, con registro y conciliación, en Grupo Codev hacemos ese trabajo. Mira desarrollo de APIs e integraciones y desarrollo de software personalizado.

Escríbenos por WhatsApp o por el formulario de contacto y te decimos qué hace falta en tu caso.