Enlaces de pago: guía

Qué es un enlace

Un enlace de pago es un envoltorio alrededor de los pagos. Cada cliente que paga por él recibe un pago propio, en la misma página de pago alojada que cualquier otro pago de Qvard.

Un pago es una factura con tipo de cambio fijo. El enlace es un punto de entrada reutilizable que crea esos pagos. Un enlace puede crear muchos pagos, pero no sustituye al pago.

El enlace tiene su propia moneda: la que ve y paga el cliente. Cada pago fija su tipo de cambio al crearse. Los tipos actuales están en la página «Tipos de cambio».

Crear un enlace en el panel

En el panel, abre el apartado «Enlaces de pago» y configura el enlace. Las opciones son:

• Importe: fijo, o introducido por el cliente con un mínimo y un máximo.
• Límite de pagos: sin límite, un solo pago o N pagos.
• Plazo: 1, 7 o 30 días, o sin plazo.
• Correo del comprador: no preguntar, opcional u obligatorio.

Cada enlace tiene su propia dirección: https://qvard.com/l/<slug>. El cliente la abre, elige token y red, y después ve la página de pago habitual.

Puedes descargar el enlace como código QR en PNG, para facturas impresas, recibos o carteles. El botón «Compartir» te da el enlace para enviarlo por cualquier canal.

Un enlace por cliente mediante la API

Para saber con certeza quién paga, crea un pago para cada cliente mediante la API desde tu servidor y envíale al cliente el redirectUrl de la respuesta. La clave secreta (qvard_sk_…) debe quedarse solo en tu servidor.

Ejemplo de solicitud

# Create a payment for one customer
curl -X POST https://api.qvard.com/api/v1/payment \
  -H 'x-api-key: qvard_sk_YOUR_SECRET_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"price":12499.00,"currency":"INR","id":"order-123"}'

# The response contains "data": { "redirectUrl": "https://my.qvard.com/pay/..." }
# Send that redirectUrl to the customer.

// Run on your server only: the secret key must not reach the browser
async function createPaymentLink(orderId, amount) {
  const res = await fetch('https://api.qvard.com/api/v1/payment', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.QVARD_SECRET_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ price: amount, currency: 'INR', id: orderId })
  });
  if (!res.ok) throw new Error('Qvard API error: ' + res.status);
  const payment = await res.json();
  return payment.data.redirectUrl; // send this link to the customer
}

// Usage inside an async handler: const link = await createPaymentLink('order-123', 10);

La respuesta incluye el id del pago y un redirectUrl, por ejemplo https://my.qvard.com/pay/<uuid>. Envía al cliente el redirectUrl. El valor de id en la solicitud es tu número de pedido.

Nunca pongas la clave secreta (qvard_sk_…) en código que se ejecute en el navegador ni en un repositorio público. Crea los pagos solo desde el servidor.

Venta limitada y enlace de un solo uso

Un enlace de un solo uso acepta un pago, lo que encaja con una factura. Un enlace con límite de N pagos acepta N pagos y luego se detiene, lo que encaja con una oferta limitada, por ejemplo 100 plazas.

Estados del enlace

• Activo: el enlace acepta pagos.
• Desactivado: lo apagaste en el panel. No acepta pagos hasta que lo vuelvas a activar.
• Caducado: pasó el plazo (1, 7 o 30 días).
• Agotado: se alcanzó el límite de pagos.

Webhook de pagos desde un enlace

Los pagos creados desde un enlace usan el mismo webhook y la misma cabecera X-Qvard-Signature. Su cuerpo tiene dos campos extra opcionales: paymentLink, que es el slug del enlace, y customerEmail, que es el correo que introdujo el cliente si el enlace lo pedía. Los pagos que no vienen de un enlace no tienen estos campos.

Cómo verificar la firma del webhook

Lo que el enlace no dice

Un enlace reutilizable no muestra quién pagó. El webhook informa del pago, no del comprador.

El campo customerEmail es opcional y no se verifica: lo escribe el cliente y nadie lo comprueba. Si necesitas saber quién es el comprador, crea un pago por API para cada comprador.

Referencia de la API