Pagos cripto para tiendas de bienes digitales

Una tienda que vende claves de licencia, cuentas de juegos, descargas o accesos tiene una propiedad poco habitual: el producto se entrega en el instante en que llega el dinero, sin nadie en medio. Por eso encaja con las criptomonedas, y por eso los detalles del flujo de pago importan. Esta guía explica qué cambia, cómo vincular la entrega al estado del pago y qué errores hacen perder existencias a las tiendas digitales.

Por qué los bienes digitales y las criptomonedas encajan

Tres propiedades de los bienes digitales coinciden con cómo funcionan los pagos cripto:

La entrega es instantánea, así que el pago también debe serlo. Un cliente que espera una clave no quiere esperar a que un banco liquide. Un pago cripto es definitivo cuando la red lo confirma, y tu sistema puede entregar de inmediato.
La audiencia ya está ahí. Quienes compran claves de software, objetos de juegos, acceso VPN, hosting y productos similares suelen tener stablecoins y preferir pagar con ellas, incluidos clientes de países donde las tarjetas de tu mercado no funcionan.
No hay contracargos de tarjeta. El remitente no puede revertir una transferencia cripto. Para una tienda que ya ha sufrido pagos con tarjeta disputados en artículos baratos de entrega instantánea, es un cambio real. También significa que un reembolso es una decisión tuya y una transferencia que envías tú, así que escribe tu política de reembolsos antes de lanzar.

El precio sigue siendo sencillo: lo fijas en dólares estadounidenses y el cliente paga el equivalente en el activo y la red que elija en la página de pago.

El flujo desde el carrito hasta el producto entregado

El recorrido de un pedido es así:

El cliente añade un producto e introduce un correo electrónico (o inicia sesión).
En el checkout elige «Pagar con cripto». Tu servidor crea un pago para el pedido y recibe un enlace a la página de pago alojada.
Rediriges al cliente a esa página. Elige un activo y una red y paga el importe exacto desde su propia billetera.
Cuando el pago se completa, la pasarela llama a tu webhook.
Tu servidor marca el pedido como pagado, toma una clave o concede acceso y la envía por correo y en la página del pedido.

Tu tienda nunca genera una dirección, vigila una blockchain ni compara importes. Hace dos cosas: crear un pago y reaccionar al estado final. La versión paso a paso con código está en cómo aceptar pagos cripto en un sitio web.

Crea el pago con tu propio número de pedido

Crea el pago desde tu backend con un único POST a https://api.qvard.com/api/v1/payment. La solicitud lleva tu clave en la cabecera Authorization: Bearer y un JSON con el número de pedido como id, el price en dólares estadounidenses y, opcionalmente, un paymentSystemId si quieres que la página se abra con un activo y una red concretos. La respuesta es 201 con un redirectUrl.

Usa un número de pedido que exista en tu sistema antes que el pago, y uno por compra. Si la solicitud excede el tiempo de espera y la repites con el mismo id para el mismo método de pago, recibes el pago existente en lugar de un segundo, así que reintentar es seguro.

Crea el pago solo cuando el cliente haya pulsado pagar, no al armar el carrito. De lo contrario, tus carritos abandonados aparecerán como un montón de pagos sin abonar.

Entrega solo con un pago completo y solo una vez

Esta es la regla que protege tus existencias. Un pago tiene cuatro estados: wait (creado), partial (el cliente envió menos de lo requerido), completed (llegó el importe completo) y rejected. Qvard llama a tu webhook cuando un pago se completa, con el id que enviaste y el status.

De ahí se derivan dos requisitos para tu manejador:

Actúa solo con completed. Nunca entregues una clave porque el cliente haya vuelto a tu sitio, ni con un importe parcial. La prueba de pago la da el webhook, no el navegador.
Sé idempotente. El webhook se reintenta hasta que tu endpoint responde exactamente HTTP 200 (cinco intentos en unos seis minutos), y un reintento puede llegar después de que el primero haya tenido éxito. Entrega la clave y marca el pedido como entregado en una sola transacción de base de datos, y omite los pedidos ya entregados. Si no, un pago puede costarte dos claves.

Comprueba la firma X-Qvard-Signature de cada webhook: HMAC-SHA256 con tu clave secreta, comparada en tiempo constante; rechaza las que no coincidan. Más en cómo proteger los webhooks de pagos cripto.

Node.jsdeliver.js

// Called from the Qvard webhook handler after the X-Qvard-Signature check.
async function onQvardEvent({ id, status }) {
  const order = await db.orders.findById(id);
  if (!order) return;                          // unknown order: ignore

  if (status !== 'completed') return;          // deliver only on a full payment
  if (order.deliveredAt) return;               // the webhook can arrive twice

  // One transaction: take a key and mark the order, so a retry cannot take a second key.
  await db.transaction(async (tx) => {
    const key = await tx.licenseKeys.takeFree(order.productId);
    await tx.orders.update(order.id, { state: 'paid', deliveredAt: new Date(), keyId: key.id });
    await mailer.send(order.email, 'Your purchase', 'Key: ' + key.value);
  });
}

Muestra al cliente lo que está pasando

Todavía no hay URL de retorno tras el pago, así que el cliente que ha pagado vuelve a tu sitio por su cuenta, a menudo unos segundos antes de que tu webhook se haya procesado. Prepárate para ese momento:

Da a cada pedido una página que muestre el estado actual: esperando pago, pagado y entregado, o un problema.
Haz que la página se actualice sola mientras el estado sea de espera, para que la clave aparezca sin recargar.
Envía también la clave por correo. La gente cierra pestañas, y el correo es la copia que buscarán después.
Si el pedido aún no está marcado como pagado, dilo con claridad y pide al cliente que no pague dos veces.

La mayoría de los tickets de soporte en las tiendas digitales son «pagué y no recibí nada». Una página de estado y un correo son lo que más los reduce.

Pagos incompletos y pedidos caducados

Los clientes cripto a veces envían algo menos de lo requerido, porque se descontó la comisión de retiro de un exchange, o pagan más tarde de lo previsto. Decide qué hacer antes de que ocurra.

Pago parcial. El estado es partial. No entregues. Lo habitual es mantener el pedido abierto y pedir al cliente que envíe el resto, o reembolsar y cancelar. Elige una opción e informa al cliente en la página del pedido.
Tipo de cambio y tiempo. El tipo de cambio de la página de pago queda fijado durante una hora, así que el importe no se mueve mientras el cliente paga. Reserva las existencias del pedido al menos ese tiempo y libéralas si el pedido nunca se paga.
Existencias limitadas. Si queda una sola clave, resérvala al crear el pago y libérala al caducar; de lo contrario, dos clientes pueden pagar la misma clave.

Mantén la lógica pequeña. Una tienda con exactamente tres resultados (pagado, parcial, no pagado) es más fácil de gestionar que una con una docena de casos especiales.

Qué decir a los clientes

Una página de pago clara convierte mejor que una ingeniosa. Junto al botón, indica:

qué activos y redes aceptas (consulta las monedas admitidas) y que el cliente debe pagar en la red que eligió en la página de pago;
que la entrega es automática cuando el pago se completa, y dónde aparecerá la clave;
tu regla de reembolso en una frase, ya que el cliente no puede revertir un pago cripto.

Indica también el precio en dólares y deja que la página de pago muestre el importe exacto en el activo elegido. No cites tú el importe en cripto en la página del producto; cambia con el tipo de cambio.

Qué está listo hoy en Qvard y qué no

Sé realista sobre lo que estás integrando. Qvard funciona a través de su API: tu tienda crea el pago y recibe el webhook. Todavía no hay un plugin listo para plataformas de tiendas, los enlaces de pago y un sandbox independiente están en desarrollo, y los clientes vuelven a tu sitio por su cuenta tras pagar. Para una tienda con un desarrollador, o una hora de un freelancer, es un pequeño fragmento de código. Consulta la documentación para desarrolladores y la vista general de integraciones, y mira una factura de demostración para ver lo que verá tu cliente.

En cuanto al dinero, los fondos quedan en tu saldo de Qvard y los retiras a tu propia billetera; el retiro cuesta solo la comisión de red, y no hay cuota de suscripción. El retiro a una cuenta bancaria en moneda fiat no está disponible.

FAQ

¿Puedo entregar el producto automáticamente tras un pago cripto?

Sí. Qvard llama a tu webhook cuando el pago se completa, y tu servidor puede entonces tomar una clave o conceder acceso y enviarlo al cliente. Entrega solo con el estado completed y haz que el manejador sea seguro si se ejecuta dos veces.

¿Qué pasa si el cliente envía menos del importe completo?

El pago recibe el estado partial y no se envía el webhook de finalización. No entregues. Pide al cliente que envíe el resto o reembólsalo, según indique tu política.

¿Hay contracargos con los pagos cripto?

No. El remitente no puede revertir una transferencia cripto. Eso te protege de los pagos con tarjeta disputados, pero también significa que los reembolsos los envías tú, así que define una política de reembolsos desde el principio.

¿Puedo fijar los precios en dólares?

Sí, el precio se fija en dólares estadounidenses. El cliente paga el equivalente en el activo y la red que elija en la página de pago, a un tipo de cambio fijado durante una hora.

¿Hay un plugin para mi plataforma de tienda?

Todavía no. Hoy la integración se hace por la API: una solicitud para crear un pago y un webhook para recibir el resultado.