Widget de pagamento cripto: como adicioná-lo ao seu site
Guia do widget de pagamento cripto: integre o checkout incorporado da Qvard no seu site. Criação de pagamentos no servidor e navegador, verificação de assinatura de webhook, demo.
Um widget de pagamento cripto é um widget JavaScript que abre uma janela de pagamento no seu site. O widget da Qvard agora está ao vivo em https://qvard.com/checkout.js. Este guia explica como funciona e como integrá-lo.
O que é um widget de pagamento cripto
Um widget é um elemento de pagamento compacto que o site incorpora para iniciar um pagamento. Na Qvard, o widget abre a mesma página de pagamento que seus clientes veem em uma janela modal ou formulário incorporado. O cliente escolhe o ativo e a rede; o valor é definido pelo seu pedido.
Como funciona na Qvard
O widget é carregado de https://qvard.com/checkout.js e abre uma janela de pagamento no modo modal (janela flutuante) ou incorporado. A janela é a mesma página de pagamento da Qvard: o cliente escolhe o ativo e a rede a uma taxa fixa durante a duração da fatura. Uma instância do widget recebe sua chave pública (qvard_pk_…) para criação no navegador, ou um id de pagamento para criação no servidor. Experimente na página de demonstração.
<script src="https://qvard.com/checkout.js"></script>
new QvardCheckout({
mode: 'modal',
publishableKey: 'qvard_pk_…',
price: 10,
onSuccess: function (e) {
console.log('paid', e.paymentId);
}
}).open();Duas formas de criar o pagamento
No navegador: passe a chave pública (qvard_pk_…) e o valor ao widget; ele cria o pagamento e abre a janela. No servidor: seu backend cria o pagamento via POST /api/v1/payment e passa o id ao widget. Para pedidos com preço fixo ou limites de estoque, use criação no servidor para que o cliente não possa alterar o preço no navegador. Alternativamente, pule o widget e redirecione os clientes para a página de pagamento hospedada.
A chamada no backend
O seu servidor envia o id do pedido em id e o preço em USD em price, com o cabeçalho x-api-key. A resposta traz o id do pagamento e o redirectUrl. Passe o id ao widget no navegador, ou use o redirectUrl para uma redireção. Nunca envie a chave secreta (qvard_sk_…) para o navegador.
Verifique o pagamento pelo webhook
Quando o status for paid, o seu endpoint de webhook recebe o id e o status, assinados com o cabeçalho X-Qvard-Signature (HMAC-SHA256). Verifique a assinatura usando sua chave secreta (qvard_sk_…) e confirme que o valor corresponde ao seu pedido. Marque o pedido como pago apenas após verificar a assinatura. Nota: o evento onSuccess do widget não é prova de pagamento.
Quando escolher a janela incorporada
Use o modal incorporado ou o formulário integrado para manter os clientes na sua página. A página de pagamento hospedada com redirecionamento funciona igualmente bem e é uma opção se preferir não incorporar a janela de pagamento. Ambas as abordagens compartilham a mesma API e webhook.
FAQ
O widget de pagamento cripto da Qvard está disponível hoje?
Sim. Carregue o widget de https://qvard.com/checkout.js e passe sua chave pública (qvard_pk_…) para criação no navegador, ou crie o pagamento no servidor e passe o id.
Como adiciono o widget ao meu site?
Inclua a tag <script src="https://qvard.com/checkout.js"></script> e instancie QvardCheckout com sua chave, valor e modo (modal ou incorporado). Veja os exemplos de código neste artigo e na demo.
O widget mantém o cliente no meu site?
Sim, no modo modal ou incorporado. O redirecionamento para a página hospedada leva o cliente para outro site, mas ele retorna por um link quando o pagamento é concluído.
Como testo o fluxo?
Crie um pagamento de demonstração e confirme que o seu manipulador de webhook recebe o status assinado e o valor corresponde, antes de ir ao ar.
