Pagamentos em cripto para lojas de bens digitais

Uma loja que vende chaves de licença, contas de jogos, downloads ou acessos tem uma propriedade incomum: o produto é entregue no instante em que o dinheiro chega, sem ninguém no meio. É exatamente por isso que as criptomoedas se encaixam, e é por isso que os detalhes do fluxo de pagamento importam. Este guia explica o que muda, como ligar a entrega ao estado do pagamento e que erros fazem lojas digitais perder estoque.

Por que bens digitais e cripto combinam

Três propriedades dos bens digitais coincidem com o funcionamento dos pagamentos em cripto:

A entrega é instantânea, então o pagamento também deve ser. Um cliente que espera uma chave não quer esperar a liquidação de um banco. Um pagamento em cripto é definitivo quando a rede o confirma, e seu sistema pode entregar na hora.
O público já está lá. Compradores de chaves de software, itens de jogos, acesso a VPN, hospedagem e produtos semelhantes costumam ter stablecoins e preferir pagar com elas, incluindo clientes de países onde os cartões do seu mercado não funcionam.
Não há chargebacks de cartão. O remetente não pode reverter uma transferência em cripto. Para uma loja que já sofreu com pagamentos de cartão contestados em itens baratos de entrega instantânea, é uma mudança real. Isso também significa que o reembolso é uma decisão sua e uma transferência que você mesmo envia, então escreva sua política de reembolso antes de lançar.

O preço continua simples: você o define em dólares americanos e o cliente paga o equivalente no ativo e na rede que escolher na página de pagamento.

O fluxo do carrinho ao produto entregue

O caminho de um pedido é este:

O cliente adiciona um produto e informa um e-mail (ou faz login).
No checkout, escolhe «Pagar com cripto». Seu servidor cria um pagamento para o pedido e recebe um link para a página de pagamento hospedada.
Você redireciona o cliente para essa página. Ele escolhe um ativo e uma rede e paga o valor exato da própria carteira.
Quando o pagamento é concluído, o gateway chama seu webhook.
Seu servidor marca o pedido como pago, pega uma chave ou concede acesso e a envia por e-mail e na página do pedido.

Sua loja nunca gera um endereço, monitora uma blockchain nem compara valores. Ela faz duas coisas: criar um pagamento e reagir ao estado final. A versão passo a passo com código está em como aceitar pagamentos em cripto em um site.

Crie o pagamento com o seu próprio número de pedido

Crie o pagamento a partir do seu backend com um único POST para https://api.qvard.com/api/v1/payment. A requisição leva sua chave no cabeçalho Authorization: Bearer e um JSON com o número do pedido como id, o price em dólares americanos e, opcionalmente, um paymentSystemId se quiser que a página abra com um ativo e uma rede específicos. A resposta é 201 com um redirectUrl.

Use um número de pedido que exista no seu sistema antes do pagamento, e um por compra. Se a requisição expirar e você a enviar de novo com o mesmo id para o mesmo método de pagamento, recebe o pagamento existente em vez de um segundo, então repetir é seguro.

Crie o pagamento só depois que o cliente clicar em pagar, não ao montar o carrinho. Caso contrário, os carrinhos abandonados aparecem como uma pilha de pagamentos não pagos.

Entregue só com pagamento completo, e só uma vez

Esta é a regra que protege seu estoque. Um pagamento tem quatro estados: wait (criado), partial (o cliente enviou menos que o necessário), completed (o valor total chegou) e rejected. A Qvard chama seu webhook quando um pagamento é concluído, com o id que você enviou e o status.

Daí decorrem dois requisitos para o seu handler:

Aja só em completed. Nunca entregue uma chave porque o cliente voltou ao seu site, nem com um valor parcial. A prova de pagamento é o webhook, não o navegador.
Seja idempotente. O webhook é reenviado até que seu endpoint responda exatamente HTTP 200 (cinco tentativas em cerca de seis minutos), e um reenvio pode chegar depois que o primeiro já deu certo. Entregue a chave e marque o pedido como entregue em uma única transação do banco de dados, e ignore pedidos já entregues. Caso contrário, um pagamento pode lhe custar duas chaves.

Confira a assinatura X-Qvard-Signature de cada webhook: HMAC-SHA256 com a sua chave secreta, comparada em tempo constante; rejeite o que não coincidir. Mais em como proteger webhooks de pagamentos em cripto.

Node.jsdeliver.js

// Called from the Qvard webhook handler after the X-Qvard-Signature check.
async function onQvardEvent({ id, status }) {
  const order = await db.orders.findById(id);
  if (!order) return;                          // unknown order: ignore

  if (status !== 'completed') return;          // deliver only on a full payment
  if (order.deliveredAt) return;               // the webhook can arrive twice

  // One transaction: take a key and mark the order, so a retry cannot take a second key.
  await db.transaction(async (tx) => {
    const key = await tx.licenseKeys.takeFree(order.productId);
    await tx.orders.update(order.id, { state: 'paid', deliveredAt: new Date(), keyId: key.id });
    await mailer.send(order.email, 'Your purchase', 'Key: ' + key.value);
  });
}

Mostre ao cliente o que está acontecendo

Ainda não há URLs de retorno após o pagamento, então o cliente que pagou volta ao seu site por conta própria, muitas vezes alguns segundos antes de o seu webhook ser processado. Prepare-se para esse momento:

Dê a cada pedido uma página que mostre o estado atual: aguardando pagamento, pago e entregue, ou um problema.
Faça a página se atualizar sozinha enquanto o estado for de espera, para a chave aparecer sem recarregar.
Envie também a chave por e-mail. As pessoas fecham abas, e o e-mail é a cópia que vão procurar depois.
Se o pedido ainda não está marcado como pago, diga isso com clareza e peça ao cliente que não pague duas vezes.

A maioria dos chamados em lojas digitais é «paguei e não recebi nada». Uma página de status e um e-mail reduzem isso mais do que qualquer outra coisa.

Pagamento a menor e pedidos expirados

Clientes de cripto às vezes enviam um pouco menos do que o necessário, porque a taxa de saque de uma corretora foi descontada do valor, ou pagam depois do planejado. Decida o que fazer antes que aconteça.

Pagamento parcial. O estado é partial. Não entregue. O comum é manter o pedido aberto e pedir ao cliente que envie o restante, ou reembolsar e cancelar. Escolha uma opção e avise o cliente na página do pedido.
Cotação e tempo. A cotação na página de pagamento fica fixa por uma hora, então o valor não muda enquanto o cliente paga. Reserve o estoque do pedido por pelo menos esse tempo e libere-o se o pedido nunca for pago.
Estoque limitado. Se sobrou uma única chave, reserve-a ao criar o pagamento e libere-a na expiração; senão, dois clientes podem pagar pela mesma chave.

Mantenha a lógica pequena. Uma loja com exatamente três resultados (pago, parcial, não pago) é mais fácil de operar do que uma com uma dúzia de casos especiais.

O que dizer aos clientes

Uma página de pagamento clara converte mais do que uma engenhosa. Perto do botão, diga:

quais ativos e redes você aceita (veja as moedas compatíveis) e que o cliente deve pagar na rede que escolheu na página de pagamento;
que a entrega é automática depois que o pagamento é concluído, e onde a chave vai aparecer;
sua regra de reembolso em uma frase, já que o cliente não pode reverter um pagamento em cripto.

Informe também o preço em dólares e deixe a página de pagamento mostrar o valor exato no ativo escolhido. Não cite você mesmo o valor em cripto na página do produto; ele muda com a cotação.

O que a Qvard já tem pronto hoje e o que não tem

Seja realista sobre o que você está integrando. A Qvard funciona pela API: sua loja cria o pagamento e recebe o webhook. Ainda não há plugin pronto para plataformas de loja, links de pagamento e um sandbox separado estão em desenvolvimento, e os clientes voltam ao seu site por conta própria depois de pagar. Para uma loja com desenvolvedor, ou uma hora de um freelancer, é um pequeno trecho de código. Veja a documentação para desenvolvedores e a visão geral das integrações, e abra uma fatura de demonstração para ver o que seu cliente verá.

Quanto ao dinheiro, os fundos ficam no seu saldo da Qvard e você os saca para a sua própria carteira; o saque custa apenas a taxa de rede, e não há mensalidade. O saque para conta bancária em moeda fiduciária não está disponível.

FAQ

Posso entregar o produto automaticamente depois de um pagamento em cripto?

Sim. A Qvard chama seu webhook quando o pagamento é concluído, e seu servidor pode então pegar uma chave ou conceder acesso e enviá-lo ao cliente. Entregue apenas no estado completed e faça o handler poder rodar duas vezes com segurança.

O que acontece se o cliente enviar menos que o valor total?

O pagamento recebe o estado partial e nenhum webhook de conclusão é enviado. Não entregue. Peça ao cliente que envie o restante ou reembolse-o, conforme sua política.

Existem chargebacks com pagamentos em cripto?

Não. O remetente não pode reverter uma transferência em cripto. Isso protege você de pagamentos de cartão contestados, mas também significa que os reembolsos são enviados por você, então defina uma política de reembolso desde o início.

Posso definir os preços em dólares?

Sim, o preço é definido em dólares americanos. O cliente paga o equivalente no ativo e na rede que escolher na página de pagamento, a uma cotação fixa por uma hora.

Existe um plugin para a minha plataforma de loja?

Ainda não. Hoje a integração é pela API: uma requisição para criar um pagamento e um webhook para receber o resultado.