Vinculação de pagamentos e divergências de valores

Esta seção descreve a regra que o serviço usa para vincular uma transação on-chain recebida a uma cobrança emitida, o que acontece quando o valor diverge e o que o lojista pode fazer nesse caso.

Os status da cobrança, os prazos e as transições de estado estão descritos em Ciclo de vida da cobrança.

A regra de correspondência de valores

Na criação da cobrança, o serviço converte o valor em fiat para cripto e trava os valores resultantes para a cobrança. Eles se tornam o identificador do pagamento: o cliente os vê no formulário de pagamento, e o serviço procura on-chain uma transação exatamente desse valor.

O valor do pagamento deve corresponder exatamente ao valor da cobrança. Não há tolerância. O valor a pagar é formado com 2 casas decimais para as stablecoins USDT e USDC e 8 casas decimais para as demais criptomoedas, e o pagamento recebido é comparado com ele com precisão. Qualquer desvio — pagamento a menor ou a maior, por menor que seja — significa que nenhuma vinculação automática vai acontecer.

Exemplo. Uma cobrança de 100.00 USD é emitida com o valor travado de 100.12 USDT.

Valor do pagamento recebido	Resultado
100.12 USDT	A cobrança passa automaticamente a Paga
100.11 USDT	Nenhuma vinculação automática
100.50 USDT	Nenhuma vinculação automática

Se várias cobranças com o mesmo valor em fiat forem emitidas para um mesmo endereço ao mesmo tempo, o serviço atribui a cada uma um valor em cripto ligeiramente diferente. A unicidade é verificada entre todas as suas cobranças em aberto naquela carteira, então um endereço pode ser usado com segurança em vários dos seus projetos — os valores não vão colidir.

As causas mais comuns de divergência são o cliente arredondar o valor à mão ou a taxa de rede ser descontada em um saque de uma exchange. Avise o cliente para transferir exatamente o valor exibido no formulário de pagamento.

O que acontece em uma divergência de valores

O serviço registra que os fundos chegaram, mas não faz nada com a cobrança:

• A cobrança não muda de status. Ela permanece em aberto até o prazo de pagamento. O cliente ainda pode fechá-la com o valor correto enquanto a janela de busca estiver aberta.
• Nenhum webhook é enviado. A notificação para a Webhook URL sai somente no momento em que a cobrança passa a Paga.
• Pagamento parcial não é rastreado. O serviço não reconhece pagamento a menor e não mantém um saldo restante na cobrança.
• Os pagamentos não são somados. Se o cliente completar um pagamento a menor com uma segunda transação pela diferença que falta, os dois pagamentos não são somados. Ambos permanecem como pagamentos separados e não vinculados.
• Pagamento a maior não é reembolsado automaticamente. Os fundos vão direto para a sua carteira; devolver a diferença ao cliente é resolvido fora do serviço.

Não existem no serviço status intermediários como Parcialmente paga ou Paga a maior.

Como o lojista fica sabendo do problema

Se as notificações estiverem ativadas nas configurações do projeto, o lojista recebe um e-mail e uma mensagem do bot do Telegram sobre cada pagamento recebido — tenha ele sido vinculado a uma cobrança ou não.

Disso resulta uma regra simples de diagnóstico: se chegou uma notificação de pagamento recebido mas nenhuma notificação de cobrança paga veio em seguida, o pagamento não foi vinculado por divergência de valores e precisa de tratamento manual.

A regra funciona somente dentro da janela de busca. O serviço monitora as carteiras apenas enquanto pelo menos uma cobrança ainda tem uma busca ativa. Se o cliente pagar quando não existir nenhuma cobrança assim, o pagamento nem entra no sistema — sem notificação e sem como vinculá-lo manualmente.

Você também pode encontrar pagamentos não vinculados por programação. O método payments/list retorna os pagamentos de todas as suas carteiras, e um pagamento não vinculado a uma cobrança vem sem o bloco invoice na resposta. Esses são os candidatos à vinculação manual: compare o valor e o horário com a cobrança esperada e chame invoices/bindPayment.

Vinculação manual de pagamentos

Se você tem certeza de qual pagamento corresponde a qual cobrança, vincule-os manualmente — no painel, na página da cobrança ou na lista de pagamentos, ou pela API com o método invoices/bindPayment.

Condições de vinculação

A vinculação só é possível quando todas as condições valem ao mesmo tempo:

1. A cobrança está Em aberto ou Expirada. Cobranças canceladas e já pagas não podem ser vinculadas.
2. O pagamento ainda não está vinculado a outra cobrança. Um pagamento pode ser ligado a apenas uma cobrança.
3. O pagamento chegou a uma carteira envolvida nessa cobrança.
4. O pagamento cai dentro da janela de pagamento disponível — 24 horas antes e 24 horas depois da criação da cobrança.

A janela é mais ampla que a validade da cobrança, o que abre duas possibilidades: você pode vincular um pagamento a uma cobrança já expirada e pode vincular uma cobrança a um pagamento que chegou antes de a cobrança ser criada. O segundo caso é útil quando o cliente enviou o dinheiro por conta própria e a cobrança foi emitida depois de os fundos chegarem.

O que acontece depois da vinculação

• A cobrança passa a Paga — exatamente como na vinculação automática.
• O webhook é sempre enviado. A notificação sai a cada transição para Paga, independentemente de como a vinculação foi feita.
• O valor da cobrança em USD é recalculado pelo pagamento real. O campo amountFiatUSD é sobrescrito com o valor efetivamente recebido, pela cotação do momento da vinculação. O valor original em amountFiat não muda.
• A taxa é recalculada pelo valor real. Ela é cobrada pela taxa do projeto sobre o valor que você recebeu.