Conciliação de pagamentos para lojistas cripto
Como conciliar pagamentos em cripto com seus pedidos e seu saldo: o que registrar, as conferências diárias, como achar webhooks perdidos e pagamentos a menor e como contabilizar taxas e saques.
A conciliação responde a uma pergunta: cada pedido que você considera pago corresponde a um pagamento que realmente chegou, e cada pagamento que chegou corresponde a um pedido? Com cripto não é difícil, porque cada pagamento leva o seu próprio número de pedido, mas só funciona se você registra o que importa e confere em horário fixo. Este guia mostra o que anotar, que conferências executar e como explicar as diferenças que encontrar.
O que você está conciliando
Três conjuntos de registros precisam bater:
- Seus pedidos: o que você vendeu, em dólares americanos, e quais considera pagos.
- Seu log de webhooks: as notificações que a Qvard enviou e o que você fez com cada uma.
- O painel da Qvard: os pagamentos e o saldo como o gateway os vê.
A API pública não tem rota para listar ou ler pagamentos, então você não consegue trazer o lado do gateway para um script. Você concilia seus pedidos e seu próprio log de webhooks entre si, e depois compara os totais com o que o painel mostra.
O que registrar para a conciliação ser possível
A conciliação é fácil se os dados existem e dolorosa se não.
- Use o seu próprio número de pedido como id do pagamento. Ele vai para a Qvard quando você cria o pagamento e volta no webhook, então é a chave que junta tudo.
- Registre cada webhook, com o
id, ostatus, a hora e a sua decisão: aplicado, repetição, pedido desconhecido ou chave rejeitada. Nunca registre sua chave secreta. - Guarde o valor do pedido em dólares no momento do pedido, e a hora em que o marcou como pago.
- Guarde o id do pagamento da Qvard vindo da resposta, se quiser para suporte.
Marque um pedido como pago apenas a partir do webhook, que a Qvard envia quando um pagamento está concluído, e torne o tratador idempotente. Detalhes em como proteger webhooks de pagamentos em cripto.
As conferências diárias
Três consultas pequenas pegam quase tudo; o exemplo as mostra.
- Pedidos não pagos após a janela da cotação. A cotação na página de pagamento fica fixa por uma hora. Um pedido ainda aguardando depois disso foi abandonado ou teve a notificação perdida. Olhe esses pagamentos no painel.
- Pedidos pagos sem um evento «completed». Se você marcou um pedido como pago mas seu log não tem notificação de conclusão, algo contornou o webhook, o que nunca deveria acontecer. Investigue antes de enviar mais.
- O total diário. Compare o número e a soma em dólares dos pedidos que você marcou como pagos com os pagamentos que o painel mostra para o mesmo dia.
Quando o painel mostra um pagamento como concluído e seu pedido ainda está sem pagar, a notificação foi perdida: reenvie-a pelo painel e deixe o tratador idempotente aplicá-la.
-- Your side: every webhook you receive is logged with your decision.
CREATE TABLE qvard_events (
id BIGSERIAL PRIMARY KEY,
order_id TEXT NOT NULL, -- the id you sent to Qvard
status TEXT NOT NULL, -- completed, ...
decision TEXT NOT NULL, -- applied | repeat | unknown_order | rejected_key
received_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
-- 1. Orders still unpaid after the rate window: candidates for a missed notification.
SELECT id, amount_usd, created_at
FROM orders
WHERE state = 'awaiting_payment'
AND created_at < now() - interval '1 hour'
ORDER BY created_at;
-- 2. Orders you consider paid, with no logged "completed" event: investigate before fulfilling more.
SELECT o.id, o.amount_usd, o.paid_at
FROM orders o
LEFT JOIN qvard_events e ON e.order_id = o.id AND e.status = 'completed'
WHERE o.state = 'paid' AND e.id IS NULL;
-- 3. The daily total to compare with the Qvard cabinet.
SELECT date_trunc('day', paid_at) AS day, count(*) AS orders, sum(amount_usd) AS usd
FROM orders
WHERE state = 'paid'
GROUP BY 1
ORDER BY 1 DESC;Explicar as diferenças que você encontrar
A maioria das lacunas tem uma lista curta de causas.
- Um pagamento a menor. Chegou menos que o valor total, então o pagamento tem o estado
partiale nenhum webhook de conclusão foi enviado. O pedido não está pago; peça a diferença ou reembolse. Veja como lidar com pagamentos incompletos em USDT. - Uma notificação perdida. Seu servidor ficou fora do ar por mais que a janela de novas tentativas (cinco tentativas em cerca de seis minutos), ou respondeu com algo diferente de exatamente HTTP 200. Veja estratégia de novas tentativas de webhooks em sistemas de pagamento.
- Uma duplicata. O mesmo evento chegou duas vezes. Um tratador correto o registra como repetição e não muda nada.
- Um pedido desconhecido. Uma notificação com um id que você não tem. Procure erros de digitação no id que envia e pagamentos criados de outro sistema com a mesma chave.
- Um reembolso. Um reembolso é uma transferência que você mesmo envia; registre-o contra o pedido original para que os totais continuem se explicando.
Taxas, saldos e saques
O valor em dólares dos pedidos não é o mesmo que o dinheiro na sua carteira.
- Comissão. 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%. Registre-a como uma linha própria.
- Taxas de rede. O cliente paga a taxa de rede da transferência. Você paga apenas a taxa de rede quando saca para a sua própria carteira.
- Saques. Registre cada um com data, rede e taxa. O saque para conta bancária em moeda fiduciária não está disponível; se você converte em dinheiro, essa etapa acontece fora da Qvard e tem registros próprios.
- Moeda e rede. Os pagamentos em redes diferentes se acumulam separadamente. Confira os saldos por ativo e rede, como em taxas de rede nas operações de pagamentos em cripto.
Mantenha também seu contador informado: o tratamento fiscal e contábil de recebimentos em cripto depende do seu país.
FAQ
Posso buscar meus pagamentos pela API para conciliar?
A API pública não tem rota para listar ou ler pagamentos. Concilie seus pedidos e seu próprio log de webhooks e compare os totais com os pagamentos e o saldo no painel da Qvard.
Como associo um pagamento a um pedido?
Pelo id. Você envia o número do seu próprio pedido ao criar o pagamento, e o mesmo id volta no webhook.
E se o painel mostra um pagamento concluído e meu pedido está sem pagar?
A notificação foi perdida. Reenvie-a pelo painel; um tratador idempotente a aplica com segurança.
Com que frequência devo conciliar?
Diariamente é um bom padrão, mais um alerta quando uma sequência de requisições de webhook receber erro.