Skip to Content
QvaPay API
Mini-apps

SDK window.QvaPay

Referencia completa del objeto que la app de QvaPay inyecta en tu mini-app.

No instalas nada: la app inyecta window.QvaPay antes de que cargue tu página, solo en los orígenes de tu lista de Orígenes permitidos. Fuera de la app (en un navegador normal) no existe.

if (!window.QvaPay) {
  // Abierta fuera de la app de QvaPay: muestra un aviso o tu web normal
}

Para el simulador añade <script src="https://www.qvapay.com/miniapps/sdk-sim.js"></script>. Si tu código arranca antes que ese script, espera el evento qvapay:ready:

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

Resumen

QvaPay.version            // "1"
QvaPay.launchParams       // { slug, language }
QvaPay.theme              // tema actual (en el simulador puede ser null hasta getTheme)

QvaPay.ready()            // oculta el loader nativo
QvaPay.close()            // cierra la mini-app

QvaPay.getTheme() -> Promise<{ mode: 'light'|'dark', colors: { bg, surface, text, primary } }>
QvaPay.on('themeChanged'|'backButton'|'mainButton'|'headerAction', cb)
QvaPay.off(event, cb)

QvaPay.auth.requestLogin({ scopes: ['profile','kyc'] }) -> Promise<{ init_data, hash, scopes }>  // sin scopes: ['profile']
QvaPay.payments.payInvoice(invoiceUuid) -> Promise<{ status: 'paid', transaction_uuid }>

QvaPay.ui.header.set({ subtitle, actions })                    // subtítulo y botones de la barra superior
QvaPay.ui.colors.set({ header, background })                   // color de la barra superior (+ status bar) y del fondo
QvaPay.ui.mainButton.set({ text, visible, loading, enabled })  // solo cambia lo que mandes
QvaPay.ui.backButton.set({ visible })
QvaPay.ui.haptic('light'|'medium'|'heavy'|'success'|'warning'|'error')  // por defecto 'light'
QvaPay.ui.toast(message, { type: 'info'|'success'|'error' })            // por defecto 'info'

QvaPay.openLink(url)       // abre una URL https en el navegador del sistema
QvaPay.share({ text? })    // hoja nativa de compartir con el enlace público de tu mini-app

Todos los métodos devuelven una promesa. Los que no devuelven datos resuelven null.

Ciclo de vida

  • ready(): la app muestra un loader mientras tu página carga y lo quita cuando llamas a ready() o cuando la página termina de cargar, lo que ocurra antes. Llámalo en cuanto tu interfaz pueda pintarse. No sirve para alargar el loader: si tu interfaz aún espera datos, enseña tu propio estado de carga.
  • close(): cierra la mini-app y vuelve a la app.
  • launchParams.language: el idioma de la app (es, en, pt-BR), para mostrar tu interfaz en el mismo. Es también el idioma de los message de error.

La barra superior es siempre de QvaPay y tú la personalizas: mira Encabezado.

Tema

Pinta tu mini-app con los colores de la app para que no desentone. getTheme() devuelve el tema activo y themeChanged avisa si el usuario lo cambia con tu mini-app abierta (el callback recibe el mismo objeto).

const apply = (t) => {
  document.body.style.background = t.colors.bg
  document.body.style.color = t.colors.text
}
apply(await QvaPay.getTheme())
QvaPay.on('themeChanged', apply)

Encabezado

Tu mini-app se abre con la barra superior de QvaPay. No pintes otra barra propia debajo (con tu logo, tu nombre o tu botón atrás): el usuario vería dos barras seguidas. Integra la de QvaPay:

  • Logo y nombre: los de la ficha de tu mini-app, con el check de verificada. No se cambian desde el código, porque le dicen al usuario dónde está y los revisa QvaPay. Para cambiarlos, edita la ficha en el panel.
  • Subtítulo: una línea bajo el nombre que pones tú en cada pantalla (Carrito · 3 productos, Hola, @erich…).
  • Acciones: hasta 2 botones a la derecha, con iconos del catálogo y un contador opcional.
  • Botón izquierdo: cierra o retrocede él solo (ver Botón atrás).
  • Menú ⋯: siempre está. El usuario puede marcar tu mini-app como favorita, compartirla, recargarla, abrirla en el navegador (allí no existe window.QvaPay), cerrarla y retirarle el acceso a sus datos.
QvaPay.ui.header.set({
  subtitle: 'Hola, @erich',
  actions: [
    { id: 'cart', icon: 'cart', label: 'Carrito', badge: 3 },
    { id: 'search', icon: 'search', label: 'Buscar' },
  ],
})
QvaPay.on('headerAction', ({ id }) => {
  if (id === 'cart') openCart()
  if (id === 'search') openSearch()
})

Llámalo al arrancar y cada vez que cambies de pantalla. Las reglas:

  • Como el botón principal, cada set cambia solo lo que mandas. subtitle: null (o '') quita el subtítulo y actions: [] (o null) quita los botones.
  • subtitle: una línea, hasta 48 caracteres.
  • actions: como mucho 2. Cada una lleva id (letras, números, - y _, hasta 32, sin repetir), icon del catálogo y label, que es lo que lee el lector de pantalla y es obligatorio. badge es opcional: un número, 0 no muestra nada y por encima de 99 se ve 99+.
  • Si algo no cumple las reglas, la promesa rechaza con INVALID_PARAMS y el encabezado no cambia.
  • Con dos acciones queda menos sitio para el nombre, que se corta con «…» si no cabe.

Iconos del catálogo: cart, search, filter, sort, share, heart, star, bookmark, bell, user, settings, help, plus, edit, chat, calendar, wallet, ticket, home, location, refresh. Cada plataforma los dibuja con su estilo: en iOS 26 o posterior la barra es la del sistema, con sus botones de cristal y sus símbolos.

Desde QvaPay 3.7.0. ui.header y el botón atrás automático llegan juntos en la versión 3.7.0 de la app. En versiones anteriores QvaPay.ui.header no existe: ahí sigue mostrando tu barra propia, o tu usuario se quedará sin botón atrás.

if (window.QvaPay?.ui.header) {
  document.documentElement.classList.add('in-qvapay') // tu CSS oculta tu barra propia
  QvaPay.ui.header.set({ subtitle: 'Hola, @erich' })
}

Colores

Para una mini-app inmersiva, tiñe la barra superior (con la barra de estado del teléfono, que es la misma superficie) y el fondo del host con tus colores de marca. El nombre, el logo y los botones siguen siendo los de QvaPay; el color del texto y de los iconos sobre tu barra lo elige la app por contraste, así que la barra se lee siempre.

QvaPay.ui.colors.set({ header: '#0A84FF', background: '#000000' })
QvaPay.ui.colors.set({ header: null }) // vuelve al color de la app
  • Como el encabezado, cada set cambia solo lo que mandas. null devuelve esa superficie al tema de QvaPay.
  • header: la barra superior y la barra de estado. background: lo que hay detrás de tu página mientras carga, el pie del botón principal y la zona del gesto inferior en Android. Tu página pinta su propio fondo como siempre.
  • Solo colores opacos en hexadecimal: #RRGGBB o #RGB, en mayúsculas o minúsculas. Con alfa, rgb(), nombres o cualquier otra cosa, la promesa rechaza con INVALID_PARAMS y nada cambia.
  • En iOS 26 o posterior la barra es la del sistema: los botones de cristal se posan sobre tu color.
  • Los colores son de la mini-app, no de la página (ver varias páginas). Al recargar desde el menú ⋯ vuelven los de la app.

Desde QvaPay 3.7.1. En versiones anteriores QvaPay.ui.colors no existe: compruébalo antes de usarlo.

if (window.QvaPay?.ui.colors) QvaPay.ui.colors.set({ header: '#0A84FF' })

Botones nativos

Botón principal. Una barra fija abajo con el estilo de la app. Es la mejor forma de poner la acción principal (comprar, continuar…). Cada set cambia solo los campos que mandas y conserva el resto. Sin text el botón no se muestra, y el texto se corta a 32 caracteres. Mientras loading es true el botón enseña un indicador de carga y no se puede pulsar.

Lo de cambiar solo lo que mandas es desde QvaPay 3.7.0. En versiones anteriores cada set reemplaza el botón entero, y set({ loading: true }) lo esconde. Si tu mini-app ya tiene usuarios, manda siempre text y visible junto con lo demás: así funciona en todas las versiones.

QvaPay.ui.mainButton.set({ text: 'Pagar $5.00', visible: true, enabled: true })
QvaPay.on('mainButton', async () => {
  QvaPay.ui.mainButton.set({ loading: true })
  // ...
  QvaPay.ui.mainButton.set({ loading: false })
})

Botón atrás. Desde QvaPay 3.7.0 es automático. En la página con la que se abre tu mini-app, el botón izquierdo es una X que la cierra. En cuanto tu página tiene historial (navegaste a otra página o tu router hizo pushState), se convierte en una flecha que retrocede en ese historial, igual que el botón atrás de Android. Para salir desde cualquier página, el menú ⋯ tiene Cerrar mini-app (en Android también vale mantener pulsada la flecha). Con un router que usa el historial del navegador (React Router, Vue Router, Next.js…) no tienes que hacer nada. Para pasos a los que no se debe volver (por ejemplo, tras pagar), usa history.replaceState o location.replace.

Si tu navegación no pasa por el historial (pestañas, pasos dentro de una misma URL…), toma el control con backButton.set({ visible: true }): la flecha aparece aunque no haya historial, y tanto ella como el botón atrás de Android emiten backButton en vez de retroceder o cerrar. Ocúltalo para volver al comportamiento automático.

QvaPay.ui.backButton.set({ visible: true })
QvaPay.on('backButton', () => closeCurrentStep())

Si tu mini-app tiene varias páginas. El subtítulo, las acciones, los colores, el botón principal y backButton son de la mini-app, no de la página: si navegas a otra página de tu web (una carga completa, no un cambio de ruta de una SPA), siguen como estaban, pero tus suscripciones con on() se pierden con la página anterior. En cada página vuelve a suscribirte y deja el encabezado y los botones como los necesites. Al recargar desde el menú ⋯, todo vuelve a su estado inicial.

Vibración, avisos y enlaces

QvaPay.ui.haptic('success')                       // al completar una acción
QvaPay.ui.toast('Guardado', { type: 'success' })  // aviso breve nativo
QvaPay.openLink('https://mitienda.com/ayuda')     // fuera de la app
  • toast aparece con el nombre de tu mini-app como título y tu texto debajo, para que el usuario sepa quién le habla. El texto se corta a 120 caracteres.
  • openLink solo acepta URLs https de hasta 2048 caracteres. Cualquier otra cosa rechaza con INVALID_PARAMS.

Para salir a otra web usa siempre openLink. Si tu página intenta navegar a un origen que no está en Orígenes permitidos, la app no la carga dentro de la mini-app: la abre en el navegador del sistema.

El contenedor

Tu web corre en un navegador integrado y aislado de la app:

  • Solo https. El contenido mixto (recursos http en una página https) se bloquea.
  • Tu página nunca ve la sesión de QvaPay: el token del usuario no entra en el navegador integrado y no hay cookies compartidas con la app. Las cookies de terceros están desactivadas.
  • No hay ventanas nuevas: no cuentes con window.open ni con target="_blank". Para abrir algo fuera, openLink.
  • No incrustes iframes de otros orígenes: en iOS no cargan si su origen no está en Orígenes permitidos.
  • El vídeo y el audio se reproducen dentro de la página, pero no arrancan solos con sonido: hace falta un toque del usuario.

Compartir

Cada mini-app publicada tiene una página pública en https://www.qvapay.com/apps/<slug> que la abre dentro de la app de QvaPay (o lleva a descargarla a quien no la tiene). share() abre la hoja nativa de compartir con ese enlace:

await QvaPay.share({ text: '¡Rétame en Mi Juego!' })   // texto opcional, hasta 200 caracteres

El enlace lo pone QvaPay: no puedes compartir otra URL (para salir a otra web está openLink) y text no puede contener enlaces (INVALID_PARAMS). La promesa resuelve null al compartir; si el usuario cierra la hoja rechaza con USER_CANCELLED (solo iOS lo distingue: en Android resuelve siempre). Mientras hay una hoja abierta (compartir, permiso o pago) una segunda llamada rechaza con BUSY. Sin publicar (borrador o en revisión, para ti y para tus testers) la página pública aún no existe: desde QvaPay 3.16.0, share() rechaza con NOT_ALLOWED.

Identidad y pagos

  • auth.requestLogin({ scopes }) muestra la hoja de permiso. Ver Identidad.
  • payments.payInvoice(uuid) muestra la hoja de pago con PIN. Ver Cobros. Sin publicar no cobra: rechaza con NOT_ALLOWED sin abrir la hoja.

Errores

Toda promesa rechazada lo hace con { code, message }. Decide siempre por el code.

  • El message es una frase corta en el idioma del usuario (el de launchParams.language) que puedes mostrar tal cual. Es genérica a propósito: el motivo concreto de un fallo puede incluir datos de la cuenta del usuario y nunca llega a tu mini-app. Esto es desde QvaPay 3.7.0. En versiones anteriores el message llega en inglés.
  • Excepción: INVALID_PARAMS y UNKNOWN_METHOD son errores de integración y traen un message técnico en inglés, pensado para tu consola, no para el usuario.
  • Cuando el rechazo sale de una pantalla de la app (la hoja de permiso, la de pago o el aviso de verificación de identidad), la app ya le explicó el motivo al usuario. No lo repitas: actualiza tu interfaz.
codeCuándo
USER_CANCELLEDEl usuario cerró la hoja de permiso, de pago o de compartir. No es un error: no muestres nada.
NOT_ALLOWEDLa página no está en un origen permitido, pediste un scope que tu mini-app no tiene, o el usuario aún no verificó su identidad (KYC), obligatorio para requestLogin y payInvoice. En ese último caso la app ya le enseñó cómo verificarse. También payInvoice y share mientras la mini-app no está publicada (vista previa o tester).
INVALID_PARAMSParámetros mal formados (por ejemplo un UUID de factura inválido o una URL que no es https).
UNKNOWN_METHODEl método no existe en esta versión de la app.
BUSYYa hay una hoja abierta (permiso, pago o compartir). Espera a que termine.
NETWORKSin conexión con QvaPay.
INVOICE_APP_MISMATCHLa factura no pertenece a la App de tu mini-app.
FAILEDCualquier otro rechazo: saldo insuficiente, factura pagada o caducada, límite superado… El motivo concreto lo ve el usuario en la app.
try {
  await QvaPay.share({ text: '¡Rétame en Mi Juego!' })
} catch (e) {
  if (e.code === 'USER_CANCELLED') return
  QvaPay.ui.toast(e.message, { type: 'error' })   // ya viene en el idioma del usuario
}

Para los errores de un pago, mira el ejemplo de Cobros.

Versiones de la app

QvaPay.version es la versión del protocolo del puente, no la de la app, y sigue en "1" mientras los cambios sean compatibles. Para saber si la app del usuario trae una función, comprueba que existe en vez de comparar números.

DesdeNovedades
QvaPay 3.7.0Encabezado (ui.header.set y el evento headerAction), botón atrás automático, ui.mainButton.set que cambia solo lo que mandas y message de error en el idioma del usuario.
QvaPay 3.7.1Colores (ui.colors.set): barra superior, barra de estado y fondo con tus colores.
QvaPay 3.16.0Testers: una mini-app sin publicar se puede probar por invitación, con aviso fijo de prueba. Sin publicar, payInvoice y share rechazan con NOT_ALLOWED.

Las cuatro de la 3.7.0 llegan juntas: si existe QvaPay.ui.header, la app tiene las cuatro; los colores se detectan con QvaPay.ui.colors. El simulador se comporta siempre como la versión más reciente de la app. Si tu mini-app ya tiene usuarios, sigue los avisos de compatibilidad de cada sección para que funcione también a quien aún no ha actualizado.