API de pagamentos cripto: pagamentos servidor a servidor
Guia da API de pagamentos cripto: crie um pagamento no seu servidor com POST /api/v1/payment, receba um redirectUrl e o status final por webhook.
Uma API de pagamentos cripto permite que o seu backend crie um pagamento, envie o cliente a uma página de pagamento hospedada e conheça o status final sem montar infraestrutura blockchain própria. A Qvard oferece esse fluxo como Host-to-Host API v1.
O que faz uma API de pagamentos cripto
Uma API de pagamentos cripto transforma um evento de compra no seu servidor em uma solicitação de pagamento. O seu backend envia o id do pedido e o valor na sua moeda (USD por padrão), e o gateway devolve um redirectUrl para a página de pagamento hospedada, onde o cliente escolhe o ativo e a rede. Endereços, cotações e monitoramento da blockchain ficam com o gateway.
Como é a solicitação v1 da Qvard
A chamada é um único POST para /api/v1/payment com o cabeçalho x-api-key. O campo id leva o seu próprio id de transação e price leva o valor na moeda do campo currency opcional (ISO-4217, USD por padrão). paymentSystemId é opcional e escolhe um método de pagamento quando você precisa. A resposta traz o id do pagamento e o redirectUrl.
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
}Servidor a servidor, não navegador ao gateway
A solicitação sai do seu backend, então a chave de API nunca chega ao navegador. O cliente só vê a página de pagamento hospedada depois que você o redireciona para lá. Você também confere cada pedido do seu lado antes de criar o pagamento.
O status final chega por webhook
A resposta da API confirma que o pagamento foi criado, não que foi pago. O status final é entregue na sua URL de webhook como um POST com os campos id e status, então a lógica do pedido deve agir a partir do webhook.
O que verificar antes de ir ao ar
Guarde o id do pagamento junto ao pedido, faça o manipulador do webhook seguro para rodar duas vezes e teste todo o fluxo com uma fatura de demonstração. Use o mesmo id em todas as solicitações de um pedido, para que chamadas repetidas possam ser conciliadas.
Taxas e redes
A taxa base é de 1% por pagamento e cai de forma individual até 0,1% conforme o seu volume cresce. A taxa da rede é paga à parte, na rede que o cliente escolher. A página de preços traz as condições atuais.
FAQ
API de pagamentos cripto é o mesmo que link de pagamento?
Não. Um link de pagamento é uma página para compartilhar em vendas manuais. A API cria o pagamento a partir do seu sistema e devolve um redirectUrl controlado pelo seu código.
Preciso rodar um nó de blockchain?
Não. A Qvard monitora as redes e informa o status final por webhook, então você não precisa executar nós nem scanners.
Em qual moeda o preço é informado?
O campo price é na moeda de currency (ISO-4217, por exemplo INR ou EUR); sem esse campo, é em USD. O cliente paga no ativo e na rede que escolher na página de pagamento.
Dá para testar antes de ir ao ar?
Sim. Crie uma fatura de demonstração e veja a mesma página de pagamento hospedada que os seus clientes verão.
