Précision du Règlement et Cas Limites
Gestion des Paiements Crypto Sous-Payés et Surpayés
Lorsque les clients paient depuis des plateformes d'échange centralisées (Binance, OKX, Coinbase), l'exchange déduit souvent des frais de retrait réseau de $0.80–$1.00 du montant envoyé. Découvrez comment le moteur de tolérance et les états webhook de XPayr automatisent ce rapprochement.
1. Trois Résultats Déterministes de Règlement
| Scénario | Événement Webhook | Comportement de la Passerelle et du Contrat Intelligent |
|---|---|---|
| Sous-Paiement dans la Tolérance (ex. $99 sur $100) | payment.underpaid_accepted |
Accepté automatiquement lorsque l'écart reste dans votre seuil de tolérance configuré (ex. 1 %–2 %). La commission fixe de frais fixes de 0.5% est calculée sur le montant réellement reçu. |
| Sous-Paiement Hors Tolérance (Paiement Partiel) | payment.partial_pending |
L'interface de paiement affiche le solde exact restant en temps réel afin que l'acheteur puisse envoyer un second paiement complémentaire avant l'expiration de la session, ou que le marchand l'accepte manuellement dans le Tableau de bord. |
| Règlement avec Trop-Perçu (ex. $105 sur $100) | payment.completed (overpaid_delta > 0) |
La commande est immédiatement marquée comme honorée ; la valeur exacte de overpaid_amount est enregistrée dans la charge utile du webhook et dans le dossier de preuve de paiement afin de créditer le solde client. |
2. Exemple de Charge Utile Webhook `payment.underpaid_accepted`
Vous pouvez simuler cet événement exact et inspecter ses en-têtes de signature HMAC-SHA256 en direct dans le Testeur Interactif 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. Vérification des Preuves de Sous-Paiement et de Trop-Perçu 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
});
}
SDK NPM Officiels (v0.2.0) et Serveur MCP Distant
Intégrez Plus Vite avec les Paquets Officiels XPayr et MCP sans Installation
Installez @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) depuis NPM, ou exécutez des appels d'outils JSON-RPC 2.0 en direct via POST https://xpayr.com/api/mcp.