Точность расчетов и нестандартные случаи
Обработка недоплат и переплат в криптоплатежах
При оплате с централизованных бирж (Binance, OKX, Coinbase) биржа часто удерживает комиссию сети за вывод $0.80–$1.00 из отправленной суммы. Узнайте, как механизм допусков и статусы вебхуков XPayr автоматизируют сверку таких платежей.
1. Три детерминированных сценария расчета
| Сценарий | Событие Webhook | Поведение шлюза и смарт-контракта |
|---|---|---|
| Недоплата в пределах допуска (например, $99 вместо $100) | payment.underpaid_accepted |
Принимается автоматически, если разница укладывается в настроенный порог допуска (например, 1%–2%). Фиксированная комиссия комиссией 0.5% рассчитывается от фактически полученной суммы. |
| Недоплата сверх допуска (частичная оплата) | payment.partial_pending |
Интерфейс оплаты в реальном времени показывает точную недостающую разницу, чтобы покупатель мог отправить вторую доплату до истечения сессии либо мерчант вручную подтвердил платеж в панели управления. |
| Расчет с переплатой (например, $105 вместо $100) | payment.completed (overpaid_delta > 0) |
Заказ мгновенно помечается исполненным; точное значение overpaid_amount фиксируется в полезной нагрузке вебхука и пакете платежных доказательств для зачисления разницы на баланс клиента. |
2. Пример полезной нагрузки вебхука `payment.underpaid_accepted`
Вы можете смоделировать это событие и вживую проверить заголовки подписи HMAC-SHA256 в Интерактивный тестер вебхуков:
{
"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. Проверка доказательств недоплаты и переплаты в 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
});
}
Официальные NPM SDK (v0.2.0) и удаленный MCP-сервер
Быстрая интеграция с официальными пакетами XPayr и MCP без установки
Установите @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0)или @xpayr/mcp-server (v1.0.0) из NPM или выполняйте живые вызовы инструментов JSON-RPC 2.0 через POST https://xpayr.com/api/mcp.