Mini-apps
SDK window.QvaPay
Referencia del objeto que la app de QvaPay inyecta en tu mini-app.
La app inyecta window.QvaPay antes de que cargue tu página, solo en los orígenes de allowed_origins. Fuera de la app (en un navegador normal) no existe: compruébalo antes de usarlo.
if (!window.QvaPay) {
// Abierta fuera de la app de QvaPay
}Referencia
QvaPay.version // "1"
QvaPay.ready() // oculta el loader nativo: llámalo cuando tu UI esté lista
QvaPay.close() // cierra la mini-app
QvaPay.getTheme() -> Promise<{ mode: 'light'|'dark', colors: { bg, surface, text, primary } }>
QvaPay.on('themeChanged'|'backButton'|'mainButton', cb)
QvaPay.off(event, cb)
QvaPay.auth.requestLogin({ scopes: ['profile','kyc'] }) -> Promise<{ init_data, hash, scopes }>
QvaPay.payments.payInvoice(invoiceUuid) -> Promise<{ status: 'paid', transaction_uuid }>
QvaPay.ui.mainButton.set({ text, visible, loading, enabled })
QvaPay.ui.backButton.set({ visible })
QvaPay.ui.haptic('light'|'medium'|'heavy'|'success'|'warning'|'error')
QvaPay.ui.toast(message, { type: 'info'|'success'|'error' })
QvaPay.openLink(url) // abre la URL fuera de la app (navegador del sistema)Ciclo de vida
ready(): la app muestra un loader nativo hasta que lo llames. Llámalo en cuanto tu interfaz pueda pintarse.close(): cierra el WebView y vuelve a la app.
Tema
getTheme() devuelve el tema activo de la app para que tu mini-app no desentone. Escucha themeChanged para reaccionar si el usuario lo cambia con la mini-app abierta (el callback recibe el mismo objeto).
const theme = await QvaPay.getTheme()
document.body.style.background = theme.colors.bg
QvaPay.on('themeChanged', (t) => { document.body.style.background = t.colors.bg })Botones nativos
- Botón principal: una barra fija abajo, con el estilo de la app. Configúralo con
ui.mainButton.set(...)y escuchamainButtonpara saber cuándo lo pulsan. - Botón atrás: con
ui.backButton.set({ visible: true })la flecha del encabezado (y el gesto/botón atrás de Android) emitebackButtonen lugar de cerrar la mini-app. Ocúltalo para devolver el comportamiento por defecto (cerrar).
QvaPay.ui.mainButton.set({ text: 'Pagar $5.00', visible: true, enabled: true })
QvaPay.on('mainButton', async () => {
QvaPay.ui.mainButton.set({ loading: true })
// ...
})Identidad y pagos
auth.requestLogin({ scopes })muestra al usuario una hoja de consentimiento. Ver Identidad del usuario.payments.payInvoice(uuid)muestra la hoja de pago nativa (con PIN). Ver Cobros.
Errores
Toda promesa rechazada lo hace con un objeto { code, message }:
code | Cuándo |
|---|---|
USER_CANCELLED | El usuario cerró la hoja de consentimiento o de pago. |
NOT_ALLOWED | La página no está en allowed_origins, o pediste un scope no autorizado para tu mini-app. |
INVALID_PARAMS | Parámetros mal formados (p. ej. un UUID de factura inválido). |
BUSY | Ya hay una hoja abierta (consentimiento o pago). Espera a que termine. |
NETWORK | Sin conexión con QvaPay. |
INVOICE_APP_MISMATCH | La factura no pertenece a la App de tu mini-app. |
FAILED | Cualquier otro fallo (factura pagada o caducada, saldo insuficiente…). |
try {
await QvaPay.payments.payInvoice(uuid)
} catch (e) {
if (e.code === 'USER_CANCELLED') return
QvaPay.ui.toast(e.message, { type: 'error' })
}