
Pagamentos em cripto a menos, a mais, atrasados e duplicados
Trate pagamentos parciais, excedentes, vencidos e duplicados com registros exatos, taxas por depósito e callbacks verificados da Suawave.
Publicado em , atualizado em

Antes de responder a um cliente que pagou a menos, defina sua política de valores. Salve total do pedido, ticker e depósito mínimo. Conte cada depósito confirmado elegível uma vez, usando valores exatos. Excedente, endereço vencido e webhook repetido exigem decisões distintas e nem sempre geram callback.
A API pública de criação da Suawave não recebe o total do pedido. Ela atribui um endereço ao par ticker e callback. Sua loja decide se os depósitos pagam uma compra de 25 USDT; o gateway avalia a elegibilidade de cada transferência.
Como tratar pagamentos parciais?
Um depósito de 20 USDT para um pedido de 25 USDT pode ser elegível para repasse sem quitar a compra. Já uma transferência abaixo do mínimo do ticker não é encaminhada, não gera callback e não aparece nos logs públicos.
Leia minimum_transaction_coin em GET /{ticker}/info/ ou na resposta de create. Mostre-o antes do envio e consulte novamente antes de sugerir complemento. Vale o mínimo vigente na primeira detecção.
| Situação | Gateway | Loja |
|---|---|---|
| Depósito elegível menor que o pedido | Repasse e taxas separados, callback próprio | Registrar e manter saldo em aberto |
| Depósito abaixo do mínimo | Sem repasse ou callback público | Explicar o mínimo e investigar |
| Depósito elegível acima do pedido | Repasse integral após taxas | Registrar e resolver o excedente |
| Webhook entregue novamente | Mesmo UUID | Reconhecer sem repetir efeitos |
Consulte taxas e mínimos. Salve também o limite de aceitação no pedido para uma mudança posterior de preço não alterar um checkout existente.
O cliente pode enviar o restante depois?
Pode fazer outro depósito enquanto o pedido for elegível, mas cada transferência precisa atingir o mínimo sozinha. A Suawave não soma fragmentos abaixo do mínimo para torná-los elegíveis.
Em um pedido ilustrativo de 25 USDT com 20 USDT recebidos, faltam 5 USDT. Compare esse saldo ao mínimo atual: TRC20, 10.00 USDT; BEP20, 1.00 USDT. Se o restante estiver abaixo do mínimo, encaminhe a resolução ao atendimento. Não peça automaticamente um valor maior que crie excedente sem explicação. Mostre o total exato e lembre o cliente de conferir descontos de saque na origem.
As taxas reduzem o crédito do pedido?
Escolha recebimento bruto ou repasse líquido e deixe isso explícito. value_coin é o depósito; value_forwarded_coin é o líquido após fee_coin. Não desconte a taxa novamente do valor líquido.
Uma loja que aceita valor bruto pode quitar 25 USDT com um depósito elegível de 25 USDT, absorvendo as taxas. Uma política de líquido pode exigir mais. Use strings decimais até converter para inteiros ou um tipo decimal exato. USDT TRON usa seis casas no registro; USDT BSC usa dezoito. Não suponha precisão igual em todas as redes.
E quando o cliente paga a mais?
O depósito elegível é encaminhado integralmente após taxas, sem limite pelo total da loja e sem reembolso automático. Em uma compra de 25 USDT paga com 30 USDT, a loja precisa resolver os 5 USDT excedentes.
Registre bruto, líquido e excesso conforme sua política, mantendo um estado separado de resolução. Marcar como pago não elimina o excedente dos registros.
txid_in não comprova um destino seguro para devolução: o envio pode vir de uma corretora. Obtenha e verifique o destino pelo seu processo de atendimento. A API create não é uma API de reembolso.
Duas transferências reais são dois pagamentos, cada um com taxas e callback próprios. Um segundo depósito depois de quitar o pedido gera um registro de excesso, não uma segunda entrega.
O que acontece após o vencimento?
Create retorna expires_at. Repetir o mesmo par ticker e callback retorna o vencimento original, sem estender a janela. Pare de exibir o endereço vencido e use outro callback para uma nova tentativa.
O padrão público é 24 horas, mas use o timestamp retornado. A tolerância configurável tem padrão de dois minutos; ela pertence à avaliação de elegibilidade, não a um prazo adicional anunciado ao cliente.
A Suawave usa como horário efetivo o menor entre a observação e o timestamp do bloco mais a tolerância de desvio do relógio. Finalizar depois do prazo não torna uma transferência automaticamente atrasada. Importam o horário efetivo, o vencimento e a tolerância, não a chegada do callback à loja.
Um depósito no limite ou após vencimento mais tolerância fica retido para análise. Não é creditado nem encaminhado automaticamente, não gera callback público e não aparece nos logs. Não há reembolso ou conclusão automática do pedido. O suporte precisa dos dados e do hash.
E se um operador repassar fundos retidos depois?
Uma transferência manual do operador à carteira da loja não gera callback público. A loja precisa de conciliação manual. Não prometa que toda retenção mudará o checkout para pago.
Mantenha o pedido antigo separado do substituto. Reutilizar o callback vencido não cria outra identidade: o par é permanente. Veja a referência de criação.
Como distinguir pagamento duplicado de webhook duplicado?
Uma nova entrega do mesmo evento preserva uuid. Uma transferência real adicional exige outro registro, mesmo com o mesmo valor. Eventos pendente e confirmado têm UUIDs diferentes; somar todo UUID novo contaria um depósito duas vezes. Apenas eventos confirmados contribuem para o total aceito.
Guarde o estado do depósito e impeça que um pendente atrasado desfaça a confirmação. O guia de finalidade explica essa distinção.
O que salvar na transação do banco?
Insira o UUID verificado, registre o depósito, bloqueie o pedido ao recalcular o total e salve a transição na mesma transação. Se o UUID já existir, retorne a confirmação normal sem somar nem entregar novamente.
Mantenha também uma ação durável única de entrega por pedido. Duas transferências reais simultâneas podem atingir o limite; deduplicar eventos não evita duas entregas nesse caso. Bloqueio do pedido e unicidade da tarefa resolvem essa corrida na aplicação, sem novos parâmetros de create.
Como investigar valores divergentes?
Consulte os logs com o callback original e mantenha essa URL privada: ela dá acesso aos registros. Compare-os com os eventos confirmados salvos. sent indica repasse confirmado sem reconhecimento do callback; done indica reconhecimento.
Logs vazios não provam ausência de envio. Transferências abaixo do mínimo, não suportadas e atrasadas podem faltar. Peça hash e rede, confira destino e horário e não solicite outro pagamento apenas porque não houve callback.
Antes de publicar, exercite pagamento parcial, excedente, segunda transferência real e entrega repetida. Consulte o guia de webhooks e reveja a rede oferecida em TRC20 e BEP20 se os mínimos levarem muitas compras pequenas ao atendimento.