Pagamentos em cripto no WordPress

O WordPress não tem uma forma nativa de aceitar cripto, e a Qvard ainda não tem um plugin pronto para WordPress. O que ela tem é uma API simples, e o WordPress é perfeitamente capaz de conversar com uma. Este guia mostra como conectar uma loja WooCommerce à Qvard com duas pequenas peças de código e o que verificar quando não funciona.

Plugin ou código próprio: a escolha honesta

A primeira coisa que as pessoas procuram no WordPress é um plugin, e é um instinto razoável: instalar, colar uma chave, pronto. Esta é a situação hoje.

A Qvard ainda não tem plugin para WordPress ou WooCommerce. A integração é pela API. Preferimos dizer isso a mandar você atrás de um plugin que não existe.
Plugins de terceiros para outros gateways de cripto não se conectam à Qvard. Cada plugin fala com a API do seu próprio gateway.
O caminho próprio é pequeno. Uma requisição cria um pagamento e um endpoint recebe o resultado. Um desenvolvedor WordPress escreve isso em uma ou duas horas, e você controla exatamente o que acontece com o pedido.

Se você quer uma configuração sem código, a Qvard ainda não chegou lá. Se você tem um desenvolvedor, ou pode pagar uma hora de um, continue lendo.

Como a integração funciona

O fluxo de um pedido do WooCommerce:

No checkout, o cliente escolhe «Pagar com cripto». Seu código cria um pagamento pela API da Qvard, usando o número do pedido do WooCommerce como id do pagamento.
A Qvard retorna um redirectUrl. Você envia o cliente para essa página hospedada, onde ele escolhe um ativo e uma rede e paga da própria carteira.
Quando o pagamento é concluído, a Qvard chama um endpoint do seu site.
O endpoint encontra o pedido pelo id e o marca como pago, o que permite ao WooCommerce enviar seus e-mails habituais e passar o pedido para processamento.

Seu site WordPress nunca gera endereços nem monitora a blockchain. As duas peças que você escreve são a chamada que cria o pagamento e o endpoint que recebe o resultado.

Peça 1: criar o pagamento

No WordPress, use wp_remote_post para chamar https://api.qvard.com/api/v1/payment com sua chave de API no cabeçalho Authorization: Bearer e um JSON: id (o número do pedido, como string) e price (o valor em dólares americanos). Uma chamada bem-sucedida retorna HTTP 201 com um redirectUrl.

O exemplo abaixo faz exatamente isso para um pedido do WooCommerce. Guarde a chave em wp-config.php como constante, não no tema nem nas opções do banco de dados, de onde plugins e exportações podem vazá-la.

Dois detalhes do WooCommerce importam:

Moeda. O preço é enviado em dólares americanos. Se sua loja usa outra moeda, converta o total do pedido para dólares antes da chamada, senão o cliente será cobrado por um valor errado.
Novas tentativas. Enviar o mesmo id para o mesmo método de pagamento retorna o pagamento existente, então um clique duplo ou uma requisição repetida não cria um segundo.

Conecte isso a um método de pagamento próprio, ou à etapa do checkout que trata a opção «Pagar com cripto», e redirecione o cliente para a URL retornada.

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;
}

Peça 2: receber o webhook

Registre uma rota REST no WordPress e salve o endereço dela no seu projeto da Qvard como callback URL, por exemplo https://your-site.com/wp-json/qvard/v1/webhook. Quando um pagamento é concluído, a Qvard envia um POST com o id que você informou e o status do pagamento, assinado no cabeçalho X-Qvard-Signature.

Três regras para o endpoint:

Verifique a assinatura. Confira X-Qvard-Signature (HMAC-SHA256 com a sua chave secreta) com o SDK e rejeite o que não coincidir.
Marque o pedido como pago só em completed. Um cliente que voltou ao seu site não é prova de pagamento, e o status partial significa que ele enviou menos que o necessário.
Responda exatamente HTTP 200. A Qvard trata qualquer outro status como falha e tenta de novo (cinco tentativas em cerca de seis minutos), e não segue redirecionamentos. Por causa das novas tentativas, o handler precisa poder rodar duas vezes com segurança; o is_paid() do exemplo evita concluir o pedido em duplicidade.

Mais sobre segurança em como proteger webhooks de pagamentos em 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
        },
    ) );
} );

O que costuma quebrar no WordPress

A maioria das integrações que falham no WordPress vem do ambiente, não do código:

O webhook nunca chega. Um plugin de segurança, um firewall ou uma página de «em breve» bloqueia requisições POST desconhecidas. Libere a rota e teste de fora da sua rede.
A rota retorna 404. Os links permanentes amigáveis estão desativados ou o arquivo do plugin não foi carregado. Abra a rota no navegador; 401 ou 405 significa que ela existe, 404 que não.
Cache de páginas. Garanta que seu plugin de cache e a CDN não armazenem nem reescrevam requisições para /wp-json/.
O pedido é pago duas vezes. O handler não é idempotente. Verifique is_paid() antes de concluir.
Valor errado. A moeda da loja não é o dólar americano e não houve conversão.
Respostas lentas. Plugins pesados ligados à conclusão do pedido podem atrasar sua resposta. Retorne 200 rapidamente e faça o trabalho lento depois.

Depois de pagar, o cliente volta ao seu site por conta própria, já que as URLs de retorno ainda não estão disponíveis. Dê a ele uma página de pedido que mostre o status real, em vez de uma página de agradecimento que presume sucesso.

Teste antes de entrar no ar

Abra uma fatura de demonstração para ver a página de pagamento que seu cliente receberá. Depois:

Crie um pagamento a partir de um pedido de teste e confira se recebe um redirectUrl.
Pague um pequeno valor real e confirme que o webhook chega e que o pedido fica pago.
Faça o endpoint falhar uma vez, confira se a Qvard tenta de novo e se o pedido não é concluído duas vezes.
Saque um pequeno valor do seu saldo para a sua carteira.

Ainda não há um sandbox separado, então use pequenos valores reais. Os endpoints e campos estão na documentação para desenvolvedores, e a visão geral das integrações mostra o que mais está conectado hoje.

Quanto custa manter

Não há mensalidade. Por pagamento, a comissão é individual para o seu projeto e, segundo a página de preços, começa em 1% e pode chegar a 0,1%; veja os preços para as condições atuais. Saques para a sua própria carteira custam apenas a taxa de rede. O saque para conta bancária em moeda fiduciária não está disponível.

O único custo a prever é o tempo de desenvolvimento: pouco uma vez, e alguma manutenção quando o WordPress ou o WooCommerce mudarem a forma de registrar métodos de pagamento.

FAQ

Existe um plugin da Qvard para WordPress ou WooCommerce?

Ainda não. Hoje a integração é pela API: uma requisição cria um pagamento e um webhook recebe o resultado. Um desenvolvedor WordPress consegue adicionar os dois a uma loja em uma ou duas horas.

Posso usar um plugin de cripto feito para outro gateway?

Não. Cada plugin fala com o próprio gateway e não consegue se conectar à Qvard. Você precisa de código próprio que chame a API da Qvard.

Minha loja não tem preços em dólares americanos. O que faço?

O preço é enviado à Qvard em dólares americanos, então converta o total do pedido antes de criar o pagamento. O cliente paga então o equivalente no ativo que escolher, a uma cotação fixa por uma hora.

O webhook não chega ao meu site. Por quê?

Em geral um plugin de segurança, um firewall ou uma página de manutenção bloqueia a requisição, ou a rota REST não está registrada. Confira se a rota responde de fora da sua rede e se retorna exatamente HTTP 200 a uma requisição válida.