Pagamentos em cripto para e-commerce

Para uma loja online, o cripto é um meio de pagamento adicional ao lado dos cartões, não um substituto. Ele alcança clientes cujos cartões não funcionam na sua loja, elimina os chargebacks de cartão e permite receber stablecoins em dólar. Este guia explica onde ele se encaixa no checkout, como mapear os status do pagamento para os estados do pedido, como lidar com os casos complicados e o que está pronto, e o que não está, na Qvard hoje.

O que o cripto acrescenta a uma loja, e o que não

Seja específico sobre o que espera, porque o cripto não é um interruptor de crescimento.

Clientes que suas vias de cartão não alcançam. Compradores cujos cartões bancários são recusados em lojas estrangeiras, ou que estão em países que seu processador não atende, ainda podem pagar com uma stablecoin em dólar.
Sem chargebacks de cartão. O remetente não pode reverter uma transferência em cripto, então pagamentos de cartão contestados não são um risco para esses pedidos. Um reembolso passa a ser uma transferência que você decide enviar.
Vendas internacionais sem atrito de cartão. A mesma página de pagamento funciona para um cliente em qualquer lugar.
Uma parcela modesta dos pedidos. Trate-o como uma opção adicional na página de pagamento. Na maioria das lojas ele não substituirá os cartões, e não deve complicar o fluxo de cartão.

Se você vende produtos digitais, leia pagamentos em cripto para lojas de produtos digitais; as regras de entrega de lá valem para qualquer produto instantâneo.

Onde se encaixa no checkout

Adicione «Pagar com cripto» como mais um meio de pagamento, ao lado dos existentes, e não como uma loja separada. Uma disposição simples:

O cliente preenche o carrinho e o endereço como de costume e escolhe «Pagar com cripto».
Seu servidor cria o pedido em estado pendente e um pagamento para ele.
Você redireciona o cliente para a página de pagamento hospedada, onde ele escolhe um ativo e uma rede e paga da própria carteira.
Quando o pagamento é concluído, seu servidor recebe um webhook e avança o pedido.

Mostre o preço na moeda da sua loja e cobre em dólares americanos: o pagamento é criado em dólares e o cliente paga o equivalente no ativo que escolher, a uma cotação fixada por uma hora. Se sua loja não tem preços em dólares, converta o total do pedido antes de criar o pagamento.

Crie o pagamento e use o seu 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 valor como price em dólares americanos e, opcionalmente, um paymentSystemId para abrir a página com um ativo e uma rede já selecionados. A resposta é 201 com um redirectUrl.

Use o seu próprio número de pedido como id: ele volta no webhook, então é a chave que liga o pagamento ao pedido. Se a requisição for repetida com o mesmo id para o mesmo método de pagamento, você recebe o pagamento existente, então um clique duplo ou uma requisição repetida não cria dois. O passo a passo completo com código está em como aceitar pagamentos em cripto em um site.

Mapeie os status do pagamento para os estados do pedido

Um pagamento tem quatro status, e seu pedido precisa de uma regra clara para cada um:

wait: o pagamento foi criado e o cliente não pagou. O pedido aguarda pagamento.
partial: chegou menos do que o valor total. Mantenha o pedido em espera, diga quanto falta e deixe o cliente enviar o restante, ou cancele e reembolse.
completed: chegou o valor total. É o status que aciona o webhook, e o único que deve liberar mercadoria.
rejected: o pagamento foi rejeitado. Ofereça outra forma de pagar.

O exemplo mostra o mapeamento como uma pequena tabela. Duas regras o mantêm seguro: nunca faça um pedido pago voltar a um estado anterior e nunca libere um pedido por nenhum status além de completed. O manipulador do webhook também deve ser idempotente e responder exatamente HTTP 200; veja como proteger webhooks de pagamentos em cripto.

Node.jsorder-status.js

// Qvard payment status -> your order state. Only "completed" releases goods.
const ORDER_STATE = {
  wait:      'pending_payment',   // created, the customer has not paid yet
  partial:   'on_hold',           // less than required arrived: ask for the rest or refund
  completed: 'paid',              // full amount arrived: start fulfilment
  rejected:  'payment_failed'     // rejected: offer another way to pay
};

function nextState(current, qvardStatus) {
  const target = ORDER_STATE[qvardStatus];
  if (!target) return current;                    // unknown status: change nothing
  if (current === 'paid') return current;         // never move a paid order backwards
  return target;
}

Pagamentos parciais, pedidos expirados e reembolsos

São os casos que mais tomam tempo das lojas:

Clientes que pagam menos. Muitas vezes uma taxa de saque da corretora é descontada do valor, e o pagamento chega a menor. Decida se você pede a diferença ou reembolsa, e mostre isso na página do pedido.
Clientes que pagam tarde. A cotação é fixa por uma hora. Se um pagamento chegar muito depois de o pedido ser abandonado, trate como caso de suporte em vez de automatizar.
Estoque. Se você reserva estoque para pedidos não pagos, libere-o quando o pedido expirar.
Reembolsos. Você também não consegue reverter um pagamento em cripto; um reembolso é uma transferência que você envia para a carteira do cliente. Coloque a regra nos seus termos e peça o endereço de reembolso ao cliente, em vez de tirá-lo do pagamento.
A volta ao site. Ainda não há URLs de retorno após o pagamento, então o cliente volta ao seu site por conta própria. Dê a ele uma página de pedido que mostre o status real, em vez de uma página de agradecimento que presume sucesso.

Preços, taxas e contabilidade

Mantenha simples a parte do dinheiro.

Preço em dólares, cobrança em dólares. Registre o valor do pedido em dólares no momento do pedido e guarde ao lado o id do pagamento para a conciliação.
Quanto custa. Não há mensalidade. 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%.
Como tirar o 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. O saque para conta bancária em moeda fiduciária não está disponível, então, se precisar de dinheiro em espécie, planeje uma saída por um serviço que você já usa.
Impostos e contabilidade. O tratamento de recebimentos em cripto depende do seu país; confirme com seu contador antes de lançar.

O que está pronto hoje

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. Se sua plataforma é WordPress, veja pagamentos em cripto no WordPress para código funcional. Para os ativos e redes aceitos, veja as moedas compatíveis; para os formatos de requisição, a documentação para desenvolvedores; e para ver o que seu cliente verá, abra uma fatura de demonstração.

FAQ

O cripto vai substituir os cartões na minha loja?

Não. Funciona melhor como opção adicional para clientes cujos cartões não funcionam na sua loja ou que preferem stablecoins. Mantenha o fluxo de cartão como está.

Quando devo marcar um pedido como pago?

Somente quando a Qvard enviar o webhook com o status completed. O cliente voltar ao seu site não é prova de pagamento, e o status partial significa que chegou menos que o necessário.

Como funcionam os reembolsos com cripto?

O remetente não pode reverter um pagamento em cripto, então um reembolso é uma transferência que você envia para a carteira do cliente. Defina a regra nos seus termos e peça ao cliente o endereço de reembolso.

Existe um plugin para a minha plataforma de loja?

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