Cobros
Cobra con el saldo QvaPay del usuario sin que salga de tu mini-app.
El flujo
- Tu servidor crea la factura con
POST /v2/create_invoicey las credenciales de la App de tu mini-app. Guarda eltransaction_uuidjunto a tu pedido. - Tu frontend pide el pago con el UUID de esa factura.
- El usuario confirma en la hoja de pago de la app (importe, nombre de tu App y su PIN). Si se equivoca de PIN, la hoja sigue abierta para que lo intente de nuevo: tu promesa no se resuelve hasta que paga o cierra la hoja.
- QvaPay te avisa con un webhook firmado. Solo entonces entregas el producto.
1. Crear la factura (servidor)
const res = await fetch('https://api.qvapay.com/v2/create_invoice', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'app-id': process.env.APP_ID,
'app-secret': process.env.APP_SECRET,
},
body: JSON.stringify({
amount: 5.00,
description: 'Camiseta talla M',
remote_id: 'order-12345', // tu identificador del pedido
webhook: 'https://mitienda.com/qvapay/webhook', // opcional: si no, el callback de la App
expire_at: new Date(Date.now() + 15 * 60_000).toISOString(), // opcional
}),
})
const { transaction_uuid } = await res.json()2. Pedir el pago (frontend)
try {
const { status, transaction_uuid } = await QvaPay.payments.payInvoice(invoiceUuid)
// status === 'paid': muestra "¡Gracias!" y espera la confirmación de tu servidor
} catch (e) {
if (e.code === 'BUSY') return QvaPay.ui.toast(e.message) // ya había otra hoja abierta
// USER_CANCELLED: cerró la hoja. Cualquier otro fallo del pago ya se lo explicó
// la app al usuario: aquí solo dejas tu interfaz lista para reintentar
enableBuyButton()
}La respuesta de payInvoice es solo para la interfaz. Un frontend se puede manipular: entrega el producto únicamente cuando llegue el webhook firmado o cuando tu servidor consulte la factura con /v2/transactions/:uuid.
3. Recibir el webhook (servidor)
QvaPay envía un POST al webhook de la factura, o al Callback de la App si no indicaste uno:
{
"transaction_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
"remote_id": "order-12345",
"status": "paid",
"amount": "5.00",
"signed": 0,
"created_at": "2026-10-05T12:00:00.000Z",
"updated_at": "2026-10-05T12:00:30.000Z"
}Con dos cabeceras:
x-qvapay-signature: sha256=<hex>: HMAC-SHA256 del cuerpo crudo con tuapp-secret.x-qvapay-timestamp: segundos Unix del envío.
import crypto from 'node:crypto'
// rawBody: el cuerpo EXACTO recibido (Buffer o string), antes de parsear el JSON
export function isValidQvaPayWebhook(rawBody, signatureHeader, appSecret) {
const expected = 'sha256=' + crypto.createHmac('sha256', appSecret).update(rawBody).digest('hex')
const received = String(signatureHeader || '')
return expected.length === received.length &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))
}Responde 2xx en cuanto lo guardes. Si tu servidor falla o responde 5xx o 429, reintentamos a los 5 y a los 30 segundos. Haz tu webhook idempotente: el mismo pago puede llegarte más de una vez. Usa transaction_uuid como clave.
Reglas
- Solo cobra una mini-app publicada. En borrador o en revisión (tu vista previa y tus testers)
payInvoicerechaza conNOT_ALLOWEDsin pedir el PIN; la ruta de la app responde403concode: "PREVIEW_NO_PAYMENTS". - La factura debe ser de la misma App que la mini-app. Si no, el pago falla con
INVOICE_APP_MISMATCH. - Debe estar pendiente y sin caducar (
expire_at). - El usuario necesita saldo suficiente y no puede pagar una factura de su propia cuenta.
- Pagar no requiere
requestLogin: puedes cobrar sin saber quién es el usuario. - El usuario sí necesita tener su identidad verificada (KYC) en QvaPay. Si no la tiene, la app le enseña cómo verificarse y tu promesa rechaza con
NOT_ALLOWED, sin llegar a pedirle el PIN. - Hay un máximo por pago y un máximo por usuario en 24 horas para los pagos desde mini-apps. Diseña tus importes por debajo; si necesitas más, escríbenos.
- Cada pago pasa los mismos controles de cumplimiento que una transferencia entre usuarios (sanciones, Travel Rule y, si quien cobra es nacional cubano, la certificación OFAC del pagador).
- La app protege el pago con una clave de idempotencia: un doble toque o un reintento por red caída nunca cobran dos veces.
Cualquier otro rechazo llega como FAILED, o como NETWORK si no hubo conexión. El motivo concreto (saldo insuficiente, factura caducada, límite superado…) se lo enseña la app al usuario en su propia pantalla. A tu mini-app solo llegan el código y una frase genérica en el idioma del usuario, porque ese motivo puede incluir datos de su cuenta.
Probar sin dinero real
Usa el simulador del panel de desarrollador con facturas de prueba, o activa el Modo prueba de tu App. Nunca pruebes cobros con dinero real.