Mini-apps
Publica tu web dentro de la app de QvaPay y cobra con el saldo de los usuarios en un toque.
Una mini-app es una aplicación web que tú alojas (tu dominio, tu servidor) y que la app móvil de QvaPay abre dentro de un WebView. Desde ella puedes:
- Identificar al usuario con su consentimiento, recibiendo un paquete de datos firmado (
init_data) que verificas en tu servidor. - Cobrar facturas de tu App con el saldo QvaPay del usuario: él confirma con su PIN sin salir de tu mini-app.
- Integrarte con la interfaz nativa: tema claro/oscuro, botón principal, botón atrás, vibración háptica y avisos.
Todo esto lo hace un objeto global que la app inyecta en tu página: window.QvaPay.
Cómo funciona
Cada mini-app pertenece 1:1 a una App de tu cuenta (la misma que usas para la API de comercios):
- El
app-secretde esa App firma la identidad del usuario (init_data). - Las facturas se crean con esa App (
POST /v2/create_invoice) y el webhook de la App te avisa del pago. - Una mini-app solo puede cobrar facturas de su propia App: si intentas cobrar una factura de otra App, el pago se rechaza con
INVOICE_APP_MISMATCH.
Publicación
Las mini-apps no se publican solas. El equipo de QvaPay revisa cada una y la da de alta indicando:
| Campo | Descripción |
|---|---|
slug | Identificador corto y único (mi-tienda). |
name, tagline, icon | Lo que ve el usuario en el catálogo. |
entry_url | URL https que abre el WebView. |
allowed_origins | Orígenes https (sin ruta) donde se expone window.QvaPay. El origen de entry_url debe estar incluido. Si tu mini-app navega a otro dominio, el SDK deja de estar disponible allí. |
scopes | Datos de identidad que tu mini-app puede pedir: profile y/o kyc. |
category | shopping, games, finance, services, social, tools u other. |
Mientras está en borrador (draft) no aparece en la app. Una mini-app publicada (live) aparece en el catálogo si su App está activa y habilitada. QvaPay puede suspenderla (suspended) en cualquier momento.
Para solicitar el alta escríbenos desde soporte con el UUID de tu App y los campos de la tabla.
Reglas de oro
Nunca confíes en lo que te diga tu propio frontend. La identidad se confirma verificando el hash en tu servidor, y un pago se confirma solo con el webhook o consultando la factura desde tu servidor.
- El
app-secretvive solo en tu servidor. Nunca lo incluyas en el JavaScript de la mini-app. - Las facturas se crean en tu servidor con tus credenciales de App.
- Pide solo los scopes que necesites: el usuario ve qué datos compartes y puede revocar el acceso en cualquier momento desde Ajustes.
Ejemplo
Hay una mini-app de ejemplo, estática, que ejercita todo el SDK: /miniapps/hello/index.html. No crea facturas (eso lo hace tu servidor): pega el UUID de una factura de prueba para probar el pago.