Precisão de Liquidação e Casos Extremos
Tratamento de Pagamentos Cripto a Menor e a Maior
Quando os clientes pagam a partir de corretoras centralizadas (Binance, OKX, Coinbase), a corretora geralmente desconta uma taxa de saque de rede de $0.80–$1.00 do valor enviado. Saiba como o motor de tolerância e os estados de webhook da XPayr automatizam a conciliação desses casos.
1. Três Resultados Determinísticos de Liquidação
| Cenário | Evento Webhook | Comportamento do Gateway e do Contrato Inteligente |
|---|---|---|
| Pagamento a Menor Dentro da Tolerância (ex.: $99 em $100) | payment.underpaid_accepted |
Aceito automaticamente quando a diferença está dentro do limite de tolerância configurado (ex.: 1%–2%). A taxa fixa de taxa fixa de 0.5% é calculada sobre o valor efetivamente recebido. |
| Pagamento a Menor Acima da Tolerância (Pagamento Parcial) | payment.partial_pending |
A interface de checkout exibe a diferença exata restante em tempo real para que o comprador envie uma segunda transação complementar antes da expiração da sessão, ou o lojista pode aceitar manualmente no Painel. |
| Liquidação com Pagamento a Maior (ex.: $105 em $100) | payment.completed (overpaid_delta > 0) |
O pedido é marcado como concluído imediatamente; o valor exato de overpaid_amount é registrado no payload do webhook e no pacote de evidência de pagamento para que você possa creditar o saldo na conta do cliente. |
2. Exemplo de Payload Webhook `payment.underpaid_accepted`
Você pode simular exatamente este evento e inspecionar seus cabeçalhos de assinatura HMAC-SHA256 ao vivo no Testador Interativo de Webhook:
{
"event": "payment.underpaid_accepted",
"event_id": "evt_01J9XPAYR_UNDERPAID_89A2",
"created_at": "2026-11-10T18:00:00Z",
"data": {
"session_id": "cs_live_98a7b6c5d4e3",
"order_id": "ORD-2026-8841",
"network": "tron-mainnet",
"currency": "USDT",
"expected_amount": "100.000000",
"received_amount": "99.000000",
"shortfall_amount": "1.000000",
"shortfall_percent": 1.0,
"merchant_tolerance_percent": 1.5,
"gateway_fee_amount": "0.495000",
"merchant_net_amount": "98.505000",
"tx_hash": "0x9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e",
"resolution": "auto_accepted_within_tolerance"
}
}3. Verificando Evidências de Pagamento a Menor e a Maior em Node.js
// Verify underpaid/completed settlement evidence with @xpayr/payment-evidence (v0.2.0)
import { verifyPaymentEvidence } from "@xpayr/payment-evidence";
const verification = await verifyPaymentEvidence(webhookPayload, {
webhookSecret: process.env.XPAYR_WEBHOOK_SECRET,
signatureHeader: req.headers["x-xpayr-signature"],
allowUnderpaidWithinTolerance: true
});
if (verification.valid) {
await fulfillOrder(webhookPayload.data.order_id, {
receivedAmount: webhookPayload.data.received_amount,
txHash: webhookPayload.data.tx_hash
});
}
SDKs Oficiais no NPM (v0.2.0) e Servidor MCP Remoto
Integre Mais Rápido com Pacotes Oficiais da XPayr e MCP sem Instalação
Instale @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0)ou @xpayr/mcp-server (v1.0.0) pelo NPM, ou execute chamadas de ferramentas JSON-RPC 2.0 ao vivo via POST https://xpayr.com/api/mcp.