Cómo funciona redirectUrl en la caja cripto

Qué es redirectUrl

Creas un pago con un único POST a https://api.qvard.com/api/v1/payment (la cabecera x-api-key, tu número de pedido como id, el importe como price en dólares estadounidenses). La respuesta es 201 con dos campos: id, el identificador del pago en Qvard, y redirectUrl, con la forma https://my.qvard.com/pay/<id>.

La dirección lleva a una página de pago alojada: una página gestionada por Qvard, no por tu servidor. No la construyes, no la alojas ni la mantienes. Tu tarea es llevar al cliente a esa dirección y conocer después el resultado por el webhook.

Qué ve el cliente

En la página el cliente:

1. elige un activo y una red (o encuentra el que preseleccionaste con un paymentSystemId);
2. ve la dirección y el importe exacto que debe enviar, con la red mostrada junto a la dirección;
3. envía la transferencia desde su propia billetera o exchange.

El tipo de cambio de la página queda fijado durante una hora, así que el importe no se mueve mientras el cliente paga. La página es la misma sea cual sea el aspecto de tu tienda, y ese es el punto: obtienes una caja cripto que funciona sin construirla. Para verla antes de integrar, abre una factura de demostración.

Usar el enlace en la caja

El uso estándar es una redirección desde el servidor o un botón, en tres pasos:

1. El cliente elige «Pagar con cripto». Tu servidor crea tu propio pedido y el pago de Qvard.
2. Tu servidor responde con el redirectUrl, como redirección HTTP o como un valor que tu front-end usa para navegar.
3. El navegador va a la página; el cliente paga allí.

Crea el pago después de que el cliente haya pulsado el botón, no al armar el carrito. Nunca envíes la clave API secreta al navegador: el navegador solo recibe el redirectUrl. Un ejemplo completo de botón está en botón de pago cripto para sitios web.

Usar el enlace fuera de una caja

Como la página está alojada en una dirección simple, el enlace también funciona fuera de una caja web:

• En un correo o PDF de factura, junto a los datos bancarios, para que un cliente empresarial pueda elegir pagar en cripto (consulta pagos con stablecoins para facturas B2B).
• En un chat o un mensaje de soporte, para un pago puntual creado a mano con tus propias herramientas.
• Tras un código QR, si tu propio sistema lo genera a partir de la dirección.

Trata el enlace como la entrada a ese único pago. Envíalo al cliente al que pertenece y no lo publiques. Los enlaces de pago como producto independiente sin código están en desarrollo; hoy creas el pago por la API y compartes la dirección que devuelve.

Repeticiones, reintentos y qué pasa tras el pago

• El mismo pedido dos veces. Enviar el mismo id para el mismo método de pago devuelve el pago existente, así que un doble clic o una solicitud reintentada dan el mismo pago y no un segundo.
• Todavía no hay URL de retorno. Tras pagar, el cliente no vuelve automáticamente a tu sitio; las URL de retorno aún no están disponibles. Dale una página de pedido que muestre el estado real y se actualice mientras espera.
• El resultado es el webhook. Qvard llama a tu callback URL cuando el pago está completado, con tu id y el estado. Tu endpoint debe responder exactamente HTTP 200 y ser seguro si se ejecuta dos veces. Que el cliente vuelva a tu sitio no es prueba de pago. Consulta cómo proteger los webhooks de pagos cripto.

Qué no hace el enlace

Para que no lo busques:

• No te dice el estado del pago; no hay ninguna ruta para leer un pago por su id, así que usa el webhook y tus registros.
• No devuelve al cliente a tu sitio; las URL de retorno aún no están disponibles.
• No sustituye tu página de pedido: sigues necesitando una que muestre «esperando», «parcial» o «pagado».

Los formatos de solicitud y respuesta están en API de pagos cripto para desarrolladores, y todo el flujo en cómo aceptar pagos cripto en un sitio web.

FAQ