Abwicklungspräzision & Sonderfälle
Umgang mit Unter- & Überzahlungen bei Krypto-Zahlungen
Wenn Kunden von zentralisierten Börsen (Binance, OKX, Coinbase) zahlen, zieht die Börse häufig eine Netzwerk-Auszahlungsgebühr von $0.80–$1.00 vom gesendeten Betrag ab. Erfahren Sie, wie die Toleranz-Engine und Webhook-Status von XPayr den Abgleich solcher Sonderfälle automatisieren.
1. Drei deterministische Abwicklungsergebnisse
| Szenario | Webhook-Ereignis | Gateway- & Smart-Contract-Verhalten |
|---|---|---|
| Unterzahlung innerhalb der Toleranz (z. B. $99 statt $100) | payment.underpaid_accepted |
Wird automatisch akzeptiert, wenn der Fehlbetrag innerhalb Ihrer konfigurierten Toleranzschwelle liegt (z. B. 1 %–2 %). Die pauschale 0.5% Gebühr wird auf den tatsächlich eingegangenen Betrag berechnet. |
| Unterzahlung außerhalb der Toleranz (Teilzahlung) | payment.partial_pending |
Die Checkout-Oberfläche zeigt den exakten Differenzbetrag in Echtzeit an, sodass der Käufer vor Sitzungsablauf eine zweite Nachzahlung senden oder der Händler die Zahlung manuell im Dashboard akzeptieren kann. |
| Überzahlte Abwicklung (z. B. $105 statt $100) | payment.completed (overpaid_delta > 0) |
Die Bestellung wird sofort als erfüllt markiert; der exakte overpaid_amount wird im Webhook-Payload und im Zahlungsnachweis-Paket protokolliert, damit Sie das Guthaben dem Kundenkonto gutschreiben können. |
2. Beispiel-Webhook-Payload für `payment.underpaid_accepted`
Sie können genau dieses Ereignis simulieren und seine HMAC-SHA256-Signatur-Header live prüfen im Interaktiver 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. Verifizierung von Unter- & Überzahlungsnachweisen 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
});
}
Offizielle NPM-SDKs (v0.2.0) & Remote-MCP-Server
Schneller integrieren mit offiziellen XPayr-Paketen & installationsfreiem MCP
Installieren Sie @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0)oder @xpayr/mcp-server (v1.0.0) über NPM oder führen Sie Live JSON-RPC 2.0 Tool-Aufrufe aus über POST https://xpayr.com/api/mcp.