Integração de pagamentos cripto no backend, passo a passo
Integração de pagamentos cripto no backend passo a passo: crie pagamentos no servidor, redirecione o cliente, valide webhooks e concilie pedidos.
Integrar pagamentos cripto a um backend exige três peças: uma chamada do servidor que cria o pagamento, um redirecionamento para o cliente e um webhook que fecha o pedido. Este guia percorre cada passo com a API v1 da Qvard.
Passo 1: salve o pedido primeiro
Grave o pedido no seu banco com um status como pending antes de chamar a API. Use o id do pedido no campo id, para que o pagamento e o pedido fiquem vinculados desde o início.
Passo 2: crie o pagamento
A partir do seu backend, envie POST /api/v1/payment com o cabeçalho x-api-key, o id do pedido em id e o total em price. Mantenha a chave de API na configuração do servidor, nunca no código do front-end.
Passo 3: redirecione o cliente
Guarde o redirectUrl retornado junto ao pedido e envie o cliente para lá. Na página hospedada o cliente escolhe o ativo e a rede e paga o valor exato.
x-api-key: sk_live_…
{
"id": "order_1024",
"price": 12499.00,
"currency": "INR",
"paymentSystemId": 12
}
// 201 Created
{
"data": {
"id": "8f3k2a1c",
"redirectUrl": "https://my.qvard.com/pay/8f3k2a1c"
},
"code": 201,
"message": "success",
"status": true
}Passo 4: feche o pedido pelo webhook
O seu endpoint de webhook confere o x-api-key, encontra o pedido pelo id e o marca como pago quando o status é paid. É o único ponto em que um pagamento é confirmado.
Passo 5: concilie e monitore
Faça diariamente uma verificação dos pedidos que ficaram pendentes por tempo demais e compare com os seus registros de pagamento. Registre cada resposta da API e cada webhook para o suporte.
x-api-key: sk_live_…
{ "id": "order_1024", "status": "paid" }Dicas de arquitetura
Mantenha o código de pagamentos em um serviço pequeno, separado das telas de checkout. Assim você pode trocar o manipulador de webhook ou acrescentar um segundo canal sem mexer no resto da loja.
FAQ
Quais linguagens de backend posso usar?
Qualquer uma que envie um POST HTTPS com corpo JSON e receba um webhook. A API é HTTP simples, então nenhum SDK é obrigatório.
Onde devo colocar a URL do webhook?
Use um endpoint HTTPS público no seu backend. Ele deve aceitar POST e conferir o cabeçalho x-api-key antes de atualizar um pedido.
Preciso de uma integração diferente para cada criptomoeda?
Não. O cliente escolhe o ativo e a rede na página hospedada, então o seu backend cria um pagamento em USD e lê um status.
Posso testar toda a integração antes?
Sim. Use o fluxo de fatura de demonstração para pagar uma fatura de teste e confirme que o seu manipulador de webhook roda antes de aceitar pagamentos reais.
