Settlement Precision & Edge Cases
Underpaid & Overpaid Crypto Payment Handling
When customers pay from centralized exchanges (Binance, OKX, Coinbase), the exchange often deducts a $0.80–$1.00 network withdrawal fee from the sent amount. Learn how XPayr's tolerance engine and webhook states automate edge-case reconciliation.
1. Three Deterministic Settlement Outcomes
| Scenario | Webhook Event | Gateway & Smart Contract Behavior |
|---|---|---|
| Underpaid Within Tolerance (e.g. $99 on $100) | payment.underpaid_accepted |
Automatically accepted when shortfall is within your configured tolerance threshold (e.g. 1%–2%). The flat 0.5% fee is calculated on the actual received amount. |
| Underpaid Beyond Tolerance (Partial Payment) | payment.partial_pending |
Checkout UI displays the exact remaining delta in real time so the buyer can send a second top-up transaction before session expiry, or merchant can manually accept in Dashboard. |
| Overpaid Settlement (e.g. $105 on $100) | payment.completed (overpaid_delta > 0) |
Order is marked fulfilled immediately; the exact overpaid_amount is recorded in the webhook payload and payment evidence bundle so you can credit the customer's account balance. |
2. Sample `payment.underpaid_accepted` Webhook Payload
You can simulate this exact event and inspect its HMAC-SHA256 signature headers live in the Interactive Webhook Tester:
{
"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. Verifying Underpaid & Overpaid Evidence in 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
});
}
Official NPM SDKs (v0.2.0) & Remote MCP Server
Integrate Faster with Official XPayr Packages & Zero-Install MCP
Install @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0), or @xpayr/mcp-server (v1.0.0) from NPM, or execute live JSON-RPC 2.0 tool calls via POST https://xpayr.com/api/mcp.