Integrar um checkout de stablecoins na sua loja online
Integre um checkout de stablecoins em sua loja: como usar o widget incorporado, criação de pagamento no navegador e servidor, e verificação de webhook.
Integrar um checkout de stablecoins significa colocar uma janela de pagamento em USDT ou USDC dentro da sua loja online. O widget de checkout incorporado da Qvard aceita stablecoins hoje. Seus clientes escolhem o ativo cripto e a rede na página de pagamento, e você verifica o pagamento por webhook.
O que significa checkout de stablecoins incorporado
Um checkout de stablecoins incorporado é uma janela de pagamento que se abre na sua página através de um widget JavaScript. Pode aparecer como modal (pop-up) ou incorporada em um elemento. Seus clientes permanecem na sua página e pagam com USDT ou USDC sem sair. A janela de pagamento é a mesma página Qvard em um iframe: o cliente a vê em seu idioma, escolhe o ativo stablecoin e a rede, e o valor é calculado a uma taxa fixa para sua fatura.
Como funciona na Qvard
O widget carrega de https://qvard.com/checkout.js e abre uma janela de pagamento de stablecoins como modal ou incorporada. A janela mostra ativos e redes disponíveis; o cliente escolhe, e o valor a enviar é mostrado. O widget emite eventos: onSuccess (pagamento realizado), onClose (janela fechada), onError (pagamento falhado). Uma instância do widget recebe sua chave pública (qvard_pk_...) para criação no navegador, ou o id do pagamento para criação no servidor. Experimente na página de demonstração em qvard.com.
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. O cliente pode alterar o valor no navegador, então use este método para fins informativos. Sua chave pública pode ser restringida a sites permitidos no seu painel, e as solicitações são rate-limited. No servidor: seu backend cria o pagamento via POST /api/v1/payment e passa o id do pagamento ao widget. Para pedidos com valores fixos ou críticos, use criação no servidor e sempre verifique o valor no seu webhook. Ou pule o widget e redirecione clientes para a página de pagamento hospedada.
No servidor: crie o pagamento primeiro
Seu servidor envia uma solicitação POST para /api/v1/payment com o id do pedido e o preço em USD, usando o cabeçalho x-api-key com sua chave secreta (qvard_sk_...). A resposta retorna { id, redirectUrl }. Passe o id ao widget no navegador, ou use redirectUrl para um redirecionamento. Mantenha sua chave secreta no servidor; a solicitação não deve ser feita do navegador.
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
}Verifique o pagamento pelo webhook
Quando o status é paid, seu webhook recebe { id, status }, assinados com o cabeçalho X-Qvard-Signature no formato t=...,v1=... (HMAC-SHA256 com sua chave secreta). Verifique a assinatura usando sua chave secreta (qvard_sk_...) e confirme que o valor no webhook corresponde ao seu pedido. Chaves legadas sem o prefixo qvard_sk_ também recebem o cabeçalho x-api-key. Marque o pedido como pago apenas após verificar a assinatura. Consulte o guia de assinatura na documentação da Qvard.
Quando usar a janela incorporada
Use o widget modal incorporado ou incorporado para manter o cliente na sua página e oferecer um checkout de stablecoins sem problemas. A página hospedada com redirecionamento funciona igualmente bem e é uma opção se você preferir não incorporar a janela de pagamento. Ambas compartilham o mesmo processo de criação de pagamento, fluxo de webhook e verificação de assinatura.
FAQ
O checkout de stablecoins incorporado está disponível na Qvard 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 os clientes escolhem um stablecoin e rede no widget?
Os clientes veem os ativos stablecoin e redes disponíveis na página de pagamento e escolhem qual usar. O valor a enviar é atualizado com base em sua seleção.
Por que devo verificar o valor no webhook?
O valor no webhook é a fonte de verdade da Qvard. Sempre verifique se corresponde ao seu pedido, mesmo que tenha criado o pagamento no servidor, porque o cliente selecionou o stablecoin e a rede.
Como testo antes de ir ao ar?
Use a página de demonstração em qvard.com para testar o widget e ver eventos de webhook. Confirme que seu webhook verifica a assinatura e marca o pedido como pago.
