Probar tu mini-app

Simulador en el panel de desarrollador, facturas de prueba y vista previa en tu móvil. Sin dinero real.

Tienes tres formas de probar, de la más rápida a la más real:

	Dónde	Login	Cobros
Simulador	Tu navegador, en el panel de desarrollador	Real, firmado con tu `app-secret`	Solo facturas de prueba
Modo prueba	Tu servidor contra la API real	No aplica	Las facturas de tu App se pagan solas, sin dinero real
Vista previa	Tu móvil, en la app de QvaPay	Real	Reales (ver abajo)

Simulador

Está en tu App del panel de desarrollador, sección Mini-app, pestaña Simulador. Muestra tu mini-app dentro de un móvil de prueba con el encabezado, el botón principal, las hojas de permiso y de pago, los avisos y el tema claro u oscuro de la app real.

1. Añade el puente a tu página

<script src="https://www.qvapay.com/miniapps/sdk-sim.js"></script>

Ponlo antes que tu código. El puente define window.QvaPay solo cuando tu página está dentro del simulador. Dentro de la app real no hace nada (la app ya inyectó el SDK) y en un navegador normal tampoco, así que puedes dejarlo en producción.

Si tu código comprueba window.QvaPay antes de que cargue el puente, espera el evento qvapay:ready, que emiten tanto la app como el simulador:

if (window.QvaPay) start()
else window.addEventListener('qvapay:ready', start, { once: true })

2. Deja que el simulador te incruste

El simulador abre tu página en un iframe. Si tu servidor envía X-Frame-Options o Content-Security-Policy, permite el panel de QvaPay:

Content-Security-Policy: frame-ancestors 'self' https://www.qvapay.com

3. Prueba en local

Escribe tu servidor local en URL de prueba (por ejemplo http://localhost:5173) y pulsa Abrir. No cambia tu configuración guardada: sirve para iterar sin desplegar.

Qué hace cada cosa en el simulador

Llamada	En el simulador
`auth.requestLogin`	Hoja de permiso. Al aceptar devuelve un `init_data` real, firmado con tu `app-secret` y con tu propia cuenta como usuario. Tu servidor lo verifica igual que en producción.
`payments.payInvoice`	Hoja de pago. Solo acepta facturas de prueba de tu App. Al pagar, la factura queda `paid` y QvaPay envía el webhook al callback de tu App. Vale cualquier PIN.
`ui.*`, `getTheme`, eventos	Igual que en la app. Cambia el tema con Tema claro/oscuro para probar `themeChanged`.

La consola del puente muestra cada llamada y cada respuesta, con los mismos códigos de error que la app.

Facturas de prueba

Hay dos formas de tener una:

Activa el Modo prueba de tu App. Toda factura que crees con /v2/create_invoice es de prueba. Ojo: en Modo prueba QvaPay la da por pagada al crearla y te envía el webhook en ese momento. El simulador la acepta como ya pagada.
Pulsa "Crear factura de prueba" en el simulador. Crea una factura pendiente sin necesidad de tu servidor. Copia su UUID y pásalo a payInvoice. Se paga cuando confirmas en la hoja de pago, y entonces llega el webhook.

El simulador nunca mueve dinero real. Si le pasas una factura normal (de una App sin Modo prueba), la rechaza con un error.

Vista previa en tu móvil

Mientras tu mini-app está en Borrador o En revisión, aparece en el catálogo de Mini-apps de la app de QvaPay solo para ti, con la cuenta dueña de la App. Es la prueba definitiva de cómo se ve y se comporta en un móvil de verdad.

La URL de entrada tiene que ser https y estar desplegada.
El login funciona igual que en producción.
Los cobros en la vista previa son reales y no puedes pagar tus propias facturas. Prueba los cobros en el simulador o pide a otra persona que pague una vez publicada.

Problemas frecuentes

Síntoma	Causa y solución
El simulador se queda en blanco	Tu servidor no deja que lo incrusten. Añade `frame-ancestors https://www.qvapay.com`.
"No detectamos el puente"	Falta `sdk-sim.js` en la página, o la página no es la de la URL configurada.
`NOT_ALLOWED` en todas las llamadas	La página está en un origen que no está en Orígenes permitidos.
`NOT_ALLOWED` al hacer login	Pediste un scope que tu mini-app no tiene marcado en Configuración.
El pago falla con "solo cobra facturas de prueba"	La factura es real. Activa el Modo prueba o usa una factura de prueba.
La firma de `init_data` no verifica	Estás usando el `app-secret` de otra App, o modificaste el texto antes de verificarlo. Envíalo tal cual.
No llega el webhook	El callback de tu App no es https o no es accesible desde internet. En local usa un túnel (ngrok, cloudflared).

On this page