Checkout cripto incorporado: uma janela de pagamento no seu site
Checkout cripto incorporado: integre uma janela modal ou formulário integrado ao vivo via JavaScript. Criação de pagamentos no servidor e navegador, verificação de webhook, demo.
Checkout cripto incorporado significa que a janela de pagamento abre diretamente na sua página através de um widget JavaScript. Pode ser um modal (janela flutuante) ou um formulário integrado. A Qvard fornece um widget pronto para produção em https://qvard.com/checkout.js. Este guia explica como funciona e como integrá-lo.
O que é o checkout incorporado
Um checkout incorporado é uma janela de pagamento, geralmente um modal, que abre sobre a página em que o cliente já está. O cliente mantém o contexto da loja e paga sem sair do site. A lógica do pagamento continua a mesma de uma página hospedada.
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 integrado. A janela é a mesma página de pagamento da Qvard: o cliente escolhe o ativo e a rede, e o valor é definido pelo seu pedido. 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 em https://qvard.com/en/embedded-checkout/playground/.
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.
<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();x-api-key: qvard_sk_…
{
"id": "order_1024",
"price": 149.99,
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}No servidor: crie o pagamento primeiro
O seu servidor envia o id do pedido e o preço em USD 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 um redirecionamento hospedado. Mantenha a chave no servidor, já que a requisição não deve partir do 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.
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 checkout cripto incorporado está disponível hoje na Qvard?
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 integrado). Veja os exemplos de código neste artigo e na demo.
A assinatura de pagamento é importante?
Sim. Sempre verifique o cabeçalho X-Qvard-Signature no seu webhook usando sua chave secreta, e confirme que o valor no webhook corresponde ao seu pedido.
Posso usar o redirecionamento em vez da janela integrada?
Sim. A página de pagamento hospedada no redirectUrl funciona igualmente bem e não requer widget. Ambas as abordagens usam a mesma API e webhook.
