Precisión de Liquidación y Casos Límite
Gestión de Pagos Cripto Insuficientes y en Exceso
Cuando los clientes pagan desde exchanges centralizados (Binance, OKX, Coinbase), el exchange suele descontar una comisión de retiro de red de $0.80–$1.00 del importe enviado. Descubre cómo el motor de tolerancia y los estados de webhook de XPayr automatizan la conciliación de casos límite.
1. Tres Resultados Deterministas de Liquidación
| Escenario | Evento Webhook | Comportamiento de la Pasarela y del Contrato Inteligente |
|---|---|---|
| Pago Insuficiente Dentro de Tolerancia (p. ej., $99 sobre $100) | payment.underpaid_accepted |
Se acepta automáticamente cuando el faltante está dentro del umbral de tolerancia configurado (p. ej., 1%–2%). La comisión fija de comisión fija del 0.5% se calcula sobre el importe realmente recibido. |
| Pago Insuficiente Fuera de Tolerancia (Pago Parcial) | payment.partial_pending |
La interfaz de checkout muestra la diferencia exacta pendiente en tiempo real para que el comprador envíe una segunda transacción complementaria antes de que expire la sesión, o el comercio puede aceptarla manualmente en el Panel. |
| Liquidación con Sobrepago (p. ej., $105 sobre $100) | payment.completed (overpaid_delta > 0) |
El pedido se marca como completado de inmediato; el valor exacto de overpaid_amount se registra en el payload del webhook y en el paquete de evidencia de pago para que puedas abonar el saldo en la cuenta del cliente. |
2. Ejemplo de Payload Webhook `payment.underpaid_accepted`
Puedes simular este evento exacto e inspeccionar sus encabezados de firma HMAC-SHA256 en vivo en el Probador Interactivo de Webhooks:
{
"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. Verificación de Evidencia de Subpago y Sobrepago en 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 Oficiales en NPM (v0.2.0) y Servidor MCP Remoto
Integra Más Rápido con los Paquetes Oficiales de XPayr y MCP sin Instalación
Instala @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0)o @xpayr/mcp-server (v1.0.0) desde NPM, o ejecuta llamadas a herramientas JSON-RPC 2.0 en vivo mediante POST https://xpayr.com/api/mcp.