Pagos cripto en WordPress

WordPress no tiene una forma integrada de aceptar cripto, y Qvard todavía no tiene un plugin listo para WordPress. Lo que sí tiene es una API sencilla, y WordPress puede hablar con una sin problema. Esta guía muestra cómo conectar una tienda WooCommerce a Qvard con dos pequeñas piezas de código, y qué revisar cuando no funciona.

Plugin o código propio: la elección honesta

Lo primero que se busca en WordPress es un plugin, y es un instinto razonable: instalar, pegar una clave, listo. Esta es la situación actual.

Qvard no tiene todavía un plugin para WordPress ni WooCommerce. La integración es por API. Preferimos decirlo antes que enviarte a buscar un plugin que no existe.
Los plugins de terceros para otras pasarelas cripto no se conectarán a Qvard. Cada plugin habla con la API de su propia pasarela.
El camino propio es pequeño. Una solicitud crea un pago y un endpoint recibe el resultado. Un desarrollador de WordPress puede escribirlo en una o dos horas, y controlas exactamente qué ocurre con el pedido.

Si quieres una configuración sin código, Qvard todavía no llega ahí. Si tienes un desarrollador, o puedes pagar una hora de uno, sigue leyendo.

Cómo funciona la integración

El flujo de un pedido de WooCommerce:

En el checkout el cliente elige «Pagar con cripto». Tu código crea un pago mediante la API de Qvard, usando el número de pedido de WooCommerce como id del pago.
Qvard devuelve un redirectUrl. Envías al cliente a esa página alojada, donde elige un activo y una red y paga desde su propia billetera.
Cuando el pago se completa, Qvard llama a un endpoint de tu sitio.
El endpoint busca el pedido por el id y lo marca como pagado, lo que permite a WooCommerce enviar sus correos habituales y pasar el pedido a procesando.

Tu sitio de WordPress nunca genera direcciones ni vigila la blockchain. Las dos piezas que escribes son la llamada que crea el pago y el endpoint que recibe el resultado.

Pieza 1: crear el pago

En WordPress, usa wp_remote_post para llamar a https://api.qvard.com/api/v1/payment con tu clave API en la cabecera Authorization: Bearer y un JSON: id (tu número de pedido, como cadena de texto) y price (el importe en dólares estadounidenses). Una llamada correcta devuelve HTTP 201 con un redirectUrl.

El ejemplo siguiente hace exactamente eso para un pedido de WooCommerce. Guarda la clave en wp-config.php como constante, no en el tema ni en las opciones de la base de datos, donde plugins y exportaciones pueden filtrarla.

Dos detalles de WooCommerce importan:

Moneda. El precio se envía en dólares estadounidenses. Si tu tienda usa otra moneda, convierte el total del pedido a dólares antes de la llamada, o al cliente se le pedirá un importe equivocado.
Reintentos. Enviar el mismo id para el mismo método de pago devuelve el pago existente, así que un doble clic o una solicitud repetida no crea un segundo pago.

Conéctalo a un método de pago propio, o al paso del checkout que gestiona la opción «Pagar con cripto», y redirige al cliente a la URL devuelta.

PHPqvard-create-payment.php

<?php
// Create a Qvard payment for a WooCommerce order and return the page to send the customer to.
// QVARD_API_KEY is defined in wp-config.php, never in a theme or a public repository.
function qvard_create_payment( WC_Order $order ) {
    $response = wp_remote_post( 'https://api.qvard.com/api/v1/payment', array(
        'timeout' => 15,
        'headers' => array(
            'Authorization'    => 'Bearer ' . QVARD_API_KEY,
            'Content-Type' => 'application/json',
        ),
        'body'    => wp_json_encode( array(
            'id'    => (string) $order->get_id(),   // matched again in the webhook
            'price' => (float) $order->get_total(), // US dollars
        ) ),
    ) );

    if ( is_wp_error( $response ) || 201 !== wp_remote_retrieve_response_code( $response ) ) {
        return null;
    }

    $data = json_decode( wp_remote_retrieve_body( $response ), true );
    return isset( $data['redirectUrl'] ) ? $data['redirectUrl'] : null;
}

Pieza 2: recibir el webhook

Registra una ruta REST en WordPress y guarda su dirección en tu proyecto de Qvard como callback URL, por ejemplo https://your-site.com/wp-json/qvard/v1/webhook. Cuando un pago se completa, Qvard envía un POST con el id que le diste y el status del pago, firmado en la cabecera X-Qvard-Signature.

Tres reglas para el endpoint:

Verifica la firma. Comprueba X-Qvard-Signature (HMAC-SHA256 con tu clave secreta) con el SDK y rechaza todo lo que no coincida.
Marca el pedido como pagado solo con completed. Un cliente que ha vuelto a tu sitio no es prueba de pago, y un estado partial significa que envió menos de lo requerido.
Responde exactamente HTTP 200. Qvard trata cualquier otro código de estado como un fallo y reintenta (cinco intentos en unos seis minutos), y no sigue redirecciones. Debido a los reintentos, el manejador debe poder ejecutarse dos veces sin riesgo; is_paid() en el ejemplo evita completar el pedido dos veces.

Más sobre seguridad en cómo proteger los webhooks de pagos cripto.

PHPqvard-webhook.php

<?php
// Webhook endpoint: https://your-site.com/wp-json/qvard/v1/webhook
add_action( 'rest_api_init', function () {
    register_rest_route( 'qvard/v1', '/webhook', array(
        'methods'             => 'POST',
        'permission_callback' => '__return_true', // authenticated below by the X-Qvard-Signature header
        'callback'            => function ( WP_REST_Request $request ) {
            try {
                $payload = ( new Qvard\Qvard( QVARD_API_KEY ) )->webhooks->constructEvent( $request->get_body(), $request->get_header( 'x-qvard-signature' ), QVARD_API_KEY );
            } catch ( \Exception $e ) {
                return new WP_REST_Response( null, 401 );
            }
            $order   = wc_get_order( (int) ( $payload['id'] ?? 0 ) );

            if ( $order && 'completed' === ( $payload['status'] ?? '' ) && ! $order->is_paid() ) {
                $order->payment_complete();
            }

            return new WP_REST_Response( null, 200 ); // must be exactly 200
        },
    ) );
} );

Qué suele fallar en WordPress

La mayoría de las integraciones fallidas en WordPress se deben al entorno, no al código:

El webhook nunca llega. Un plugin de seguridad, un firewall o una página de «próximamente» bloquea solicitudes POST desconocidas. Permite la ruta y pruébala desde fuera de tu red.
La ruta devuelve 404. Los enlaces permanentes amigables están desactivados o el archivo del plugin no se carga. Abre la ruta en un navegador; un 401 o 405 significa que existe, un 404 que no.
Caché de páginas. Asegúrate de que tu plugin de caché y tu CDN no almacenan ni reescriben las solicitudes a /wp-json/.
El pedido se paga dos veces. El manejador no es idempotente. Comprueba is_paid() antes de completar.
Importe equivocado. La moneda de la tienda no es el dólar estadounidense y no se hizo conversión.
Respuestas lentas. Plugins pesados enganchados a la finalización del pedido pueden retrasar tu respuesta. Devuelve 200 rápido y haz el trabajo lento después.

Tras pagar, el cliente vuelve a tu sitio por su cuenta, ya que las URL de retorno aún no están disponibles. Dale una página de pedido que muestre el estado real en lugar de una página de agradecimiento que da el éxito por hecho.

Pruébalo antes de salir en vivo

Abre una factura de demostración para ver la página de pago que recibirá tu cliente. Después:

Crea un pago desde un pedido de prueba y comprueba que recibes un redirectUrl.
Paga un pequeño importe real y confirma que llega el webhook y que el pedido pasa a pagado.
Haz que el endpoint falle una vez, comprueba que Qvard reintenta y que el pedido no se completa dos veces.
Retira un pequeño importe de tu saldo a tu billetera.

Todavía no hay un sandbox independiente, así que usa importes reales pequeños. Los endpoints y campos están en la documentación para desarrolladores, y la vista general de integraciones muestra qué más está conectado hoy.

Cuánto cuesta mantenerlo

No hay cuota de suscripción. Por pago, la comisión es individual para tu proyecto y, según la página de precios, parte del 1% y puede bajar hasta el 0,1%; consulta los precios para ver las condiciones vigentes. Los retiros a tu propia billetera cuestan solo la comisión de red. El retiro a una cuenta bancaria en moneda fiat no está disponible.

El único coste que conviene prever es el tiempo de desarrollo: poco una vez, y algo de mantenimiento cuando WordPress o WooCommerce cambien la forma de registrar métodos de pago.

FAQ

¿Hay un plugin de Qvard para WordPress o WooCommerce?

Todavía no. Hoy la integración es por la API: una solicitud crea un pago y un webhook recibe el resultado. Un desarrollador de WordPress puede añadir ambos a una tienda en una o dos horas.

¿Puedo usar un plugin cripto hecho para otra pasarela?

No. Cada plugin habla con su propia pasarela y no puede conectarse a Qvard. Necesitas código propio que llame a la API de Qvard.

Mi tienda no tiene precios en dólares estadounidenses. ¿Qué hago?

El precio se envía a Qvard en dólares estadounidenses, así que convierte el total del pedido antes de crear el pago. El cliente paga entonces el equivalente en el activo que elija, a un tipo de cambio fijado durante una hora.

El webhook no llega a mi sitio. ¿Por qué?

Normalmente un plugin de seguridad, un firewall o una página de mantenimiento bloquea la solicitud, o la ruta REST no está registrada. Comprueba que la ruta responde desde fuera de tu red y que devuelve exactamente HTTP 200 a una solicitud válida.