# 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](./invoice-lifecycle.md).

## 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.