Botón de pago

Cómo funcionaCopy Anchor Link

El botón abre el pago de QvaPay en una ventana emergente, sin que tu cliente salga de tu web. Al terminar la ventana se cierra sola, tu página recibe un evento y va a tu URL de Éxito. Tu servidor se entera por el mismo webhook firmado que una factura creada por API.

Hay dos formas de usarlo:

Antes de empezarCopy Anchor Link

1. Crea una App en Mis Aplicaciones y déjala activa.
2. Pon su Webhook URL: es la confirmación real de cada pago.
3. Pon su URL de Éxito: a ella vuelve tu cliente después de pagar. Recibe transaction_uuid y remote_id en la query.

Botón fijoCopy Anchor Link

<div data-qvapay-button="BUTTON_UUID"></div>
<script src="https://www.qvapay.com/embed/v1/button.js" async></script>

Puedes cambiar el importe o el nombre cuando quieras sin volver a pegar nada. Si desactivas un botón, deja de cobrar y tu cliente ve un aviso de que no está disponible.

Cada clic de un cliente con sesión crea una factura de la App que caduca pronto, a los 30 minutos por defecto, con remote_id BTN-<uuid del botón>-<aleatorio>. Cada factura se confirma por webhook como cualquier otra.

Con facturaCopy Anchor Link

Crea la factura desde tu servidor y pon su transaction_uuid en la página:

curl -X POST "https://api.qvapay.com/v2/create_invoice" \
  -H "app-id: TU_APP_ID" \
  -H "app-secret: TU_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 25.00, "description": "Pedido 12345", "remote_id": "order-12345" }'

<div data-qvapay-invoice="TRANSACTION_UUID"></div>
<script src="https://www.qvapay.com/embed/v1/button.js" async></script>

Nunca llames a create_invoice desde el navegador: tu app-secret quedaría a la vista.

Confirmar el pagoCopy Anchor Link

El webhook llega a tu Webhook URL con transaction_uuid, remote_id, status y amount en el cuerpo, y las cabeceras x-qvapay-signature y x-qvapay-timestamp. Consulta cómo verificar la firma HMAC.

Eventos en tu páginaCopy Anchor Link

Los eventos salen del elemento del botón y suben hasta document:

Tras qvapay:paid, el script lleva a tu cliente a redirect, que es tu URL de Éxito. Para quedarte en la página, cancela el evento:

document.addEventListener('qvapay:paid', (event) => {
  event.preventDefault()
  mostrarGracias(event.detail.transaction_uuid)
})

Con tu propio botónCopy Anchor Link

window.QvaPayButton abre el pago sin usar nuestro botón. Llámalo dentro del clic del usuario: si esperas a una petición, el navegador bloquea la ventana.

miBoton.addEventListener('click', () => {
  window.QvaPayButton.open({
    invoice: 'TRANSACTION_UUID', // o button: 'BUTTON_UUID'
    onPaid: (event) => console.log(event.detail.transaction_uuid),
    onCancel: (event) => console.log('Canceló'),
    onClose: (event) => console.log('Cerró la ventana'),
  })
})

En una aplicación de una sola página, los elementos que llegan después de cargar el script se activan con mount:

window.QvaPayButton.mount(elemento, { onPaid: (event) => console.log(event.detail) })

Casos especialesCopy Anchor Link

Si tu web usa cabeceras de seguridad, necesita:

• Content-Security-Policy: añade https://www.qvapay.com a script-src.
• Cross-Origin-Opener-Policy: usa same-origin-allow-popups. Con same-origin tu página no puede hablar con la ventana y qvapay:close salta al abrirla.

Gestionar botones por APICopy Anchor Link

Las mismas operaciones del panel, con Bearer Token en el header Authorization. No aceptan credenciales de App ni tokens de alcance limitado.

GET /app/:uuid/pay-buttonsCopy Anchor Link

Lista los botones de la App.

{
  "data": [
    {
      "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Curso de marketing",
      "description": "Acceso de por vida",
      "amount": "25.00",
      "active": true,
      "created_at": "2026-11-05T12:00:00.000Z",
      "updated_at": "2026-11-05T12:00:00.000Z"
    }
  ],
  "limit": 20
}

limit es el máximo de botones que admite cada App.

POST /app/:uuid/pay-buttonsCopy Anchor Link

Crea un botón. Devuelve 201 con { "data": { ... } }.

PATCH /app/:uuid/pay-buttons/:buttonCopy Anchor Link

Cambia name, description, amount o active. Solo los campos enviados. No hay borrado: un botón se desactiva con "active": false.

ErroresCopy Anchor Link