API de pagos cripto para desarrolladores

La API de Qvard es deliberadamente pequeña. Tres rutas cubren todo el ciclo: crear un pago, comprobar que un método de pago está disponible y enviar un pago saliente. Esta referencia describe cada una tal como funciona hoy, con los errores que encontrarás, y es honesta sobre lo que la API no tiene, para que no construyas sobre una función que no existe.

Qué cubre la API

La API pública está en https://api.qvard.com/api/v1 y tiene tres rutas:

POST /payment: crear un pago y obtener la dirección de la página de pago alojada.
GET /method/:id/info: comprobar si un método de pago de tu proyecto está listo para aceptar pagos.
POST /payout: enviar un pago saliente a una dirección cripto.

Los resultados llegan por webhook: Qvard llama a una URL que guardaste en tu proyecto cuando un pago se completa. No hay ninguna ruta para leer un pago por su id, así que el webhook es la forma de conocer el resultado. Todo lo demás, como el panel, los saldos y los ajustes, se hace en la interfaz web.

Autenticación

Cada solicitud lleva la clave API de tu proyecto en la cabecera x-api-key. No hay tokens que renovar ni OAuth. Una clave ausente o desconocida devuelve 401 con el mensaje error.wrong.api.key.

Trata la clave como una contraseña: mantenla en el servidor, en una variable de entorno o un gestor de secretos, y nunca en código de front-end ni en un repositorio público. Esa misma clave es la que Qvard te devuelve en la cabecera x-api-key del webhook, así que una filtración afecta a ambas direcciones.

Crear un pago

POST /api/v1/payment recibe un cuerpo JSON:

id (cadena, obligatorio): tu propio identificador del pedido o la factura. Vuelve en el webhook.
price (número, obligatorio): el importe en dólares estadounidenses. El cliente paga el equivalente en el activo y la red que elija.
paymentSystemId (número, opcional): un método de pago de tu proyecto. Si lo pasas, la página de pago se abre con ese activo y esa red seleccionados.

La respuesta es 201 con dos campos: id, el identificador del pago en Qvard, y redirectUrl, la dirección de la página de pago alojada, con la forma https://my.qvard.com/pay/<id>. Redirige al cliente allí, o pon el enlace en un correo.

La llamada es idempotente por id y método de pago: enviar de nuevo el mismo id para el mismo método devuelve el pago existente en lugar de crear un segundo, así que es seguro reintentar tras un tiempo de espera agotado. Ten en cuenta que el código de estado es 201, no 200.

curlcreate-payment.sh

curl -X POST https://api.qvard.com/api/v1/payment \
  -H "x-api-key: $QVARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "id": "order-1042", "price": 49.9 }'

# 201 Created
# { "id": "6f1c2d3e-...", "redirectUrl": "https://my.qvard.com/pay/6f1c2d3e-..." }

# 401 { "message": "error.wrong.api.key" }
# 400 { "message": "Error validation", "errors": { "price": "..." } }

Errores

Los errores comparten una forma, un cuerpo JSON con un message:

400: el cuerpo no superó la validación. El mensaje es Error validation y un objeto errors asocia cada campo con su primer problema, por ejemplo un id ausente o un price que no es un número. Un importe inferior al mínimo del método elegido se rechaza de la misma manera.
401: falta la cabecera x-api-key o es desconocida (error.wrong.api.key).
404: en la ruta de información del método, un id de método que no existe (error.notfound).

Registra el cuerpo completo de la respuesta ante un 4xx; el mensaje nombra el campo que hay que corregir. No reintentes un 400 ni un 401 sin cambiar algo, pero sí un tiempo de espera agotado o un 5xx, lo cual es seguro gracias a la idempotencia anterior.

Estados del pago y el webhook

Un pago tiene uno de cuatro estados: wait (creado, sin pagar), partial (llegó menos del importe completo), completed (llegó el importe completo) y rejected.

El webhook se envía cuando el pago está completado: Qvard hace un POST a la callback URL de tu proyecto con un JSON pequeño que contiene tu id y el status, y pone tu clave API en la cabecera x-api-key. Tu endpoint debe responder exactamente HTTP 200; cualquier otro estado, un tiempo de espera agotado o una redirección cuenta como entrega fallida y se reintenta, cinco intentos en total durante unos seis minutos. La cabecera es de autenticación, no una firma criptográfica, así que compárala con tu clave en tiempo constante. Haz el manejador idempotente, porque una entrega puede llegar dos veces.

Los detalles, con código, están en cómo proteger los webhooks de pagos cripto, y todo el flujo se recorre en cómo aceptar pagos cripto en un sitio web.

Comprobar que un método está listo

GET /api/v1/method/:id/info recibe el id numérico de un método de pago de tu proyecto y responde 200 con tres campos:

server: detalles sobre el estado del método.
isReady: true cuando el método está listo para aceptar un pago.
isActive: true cuando el método no está fuera de línea, aunque aún se esté poniendo al día con la red.

Úsalo antes de ofrecer un activo y una red concretos en tu caja, por ejemplo para ocultar un método temporalmente no disponible. Un id desconocido devuelve 404. Es opcional: si dejas que el cliente elija en la página de pago, no lo necesitas.

Pagos salientes

POST /api/v1/payout envía fondos de tu saldo a una dirección cripto. El cuerpo JSON tiene:

id (cadena, obligatorio): tu propio identificador del pago saliente, usado para evitar duplicados al reintentar, así que enviar el mismo id dos veces no paga dos veces.
price (número, obligatorio): el importe en la cripto del método, no en dólares.
methodId (número, obligatorio): el método de pago de tu proyecto.
address (cadena, obligatorio): la dirección de destino.
comment (cadena, opcional).

Una llamada correcta devuelve 201. Los pagos salientes mueven dinero real, así que prueba con un importe pequeño, comprueba dos veces la dirección y la red del método y confirma con Qvard que los pagos salientes por API están habilitados para tu proyecto. El retiro a una cuenta bancaria en moneda fiat no está disponible; un pago saliente va a una dirección cripto y cuesta solo la comisión de red.

Lo que la API aún no tiene

Para ahorrarte la búsqueda:

No hay un endpoint para obtener un pago por id, así que apóyate en el webhook y en tus propios registros.
No hay firma del webhook; la autenticación es la cabecera x-api-key.
No hay sandbox: un entorno de pruebas independiente está en la hoja de ruta, así que usa importes reales pequeños. Una factura de demostración muestra la página de pago sin pagar.
No hay URL de retorno tras el pago: el cliente vuelve a tu sitio por su cuenta.
No hay plugins listos para plataformas de tiendas, y los enlaces de pago están en desarrollo.

Para formatos y ejemplos, consulta la documentación para desarrolladores. Para las condiciones comerciales, la página de precios.

FAQ

¿En qué moneda fijo el precio?

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. Un pago saliente es la excepción: su importe va en la cripto del método.

¿Es seguro reintentar la creación de un pago?

Sí. Enviar el mismo id para el mismo método de pago devuelve el pago existente, así que un reintento tras un tiempo de espera agotado no crea un duplicado.

¿Cómo conozco el resultado de un pago?

Por el webhook, que se envía cuando el pago se completa. No hay ruta para leer un pago por su id, así que guarda el id que envías y empárejalo cuando llegue el webhook.

¿Hay sandbox?

Todavía no. Hay previsto un entorno de pruebas independiente. Por ahora usa importes reales pequeños y una factura de demostración para ver la página de pago.