Documentation API

Flux : créez une facture → dirigez le client vers la page de paiement → recevez un webhook signé. Préfixe /v1. Authentification via l'en-tête X-Api-Key.

Spécification OpenAPI 3 (JSON) Obtenir les clés

Réseaux pris en charge

Migrez depuis un autre processeur — sans réécrire de code

Déjà intégré avec Cryptomus / NOWPayments / Coinbase Commerce ? Changez uniquement la base-URL et la clé dans votre SDK — nous acceptons leur format create-invoice, renvoyons notre page de paiement dans leur format de réponse et émettons le webhook dans leur schéma signé, si bien que votre code de vérification fonctionne tel quel. Corrélation via order_id.

# avant:  https://api.cryptomus.com/v1/payment
# après:  https://paygate.love/compat/cryptomus/v1/payment
# clé: votre clé API paygate ; le secret du webhook = votre apiSecret paygate

Besoin d'un autre processeur ? Écrivez-nous, on ajoute l'adaptateur (c'est un seul module).

Acceptez les paiements dans votre propre bot Telegram

Votre marchand est un bot ? N'envoyez pas l'utilisateur vers un site ou un bot-portefeuille tiers. Votre bot appelle notre API, affiche l'adresse + le montant + le QR directement dans le chat, et change le message en « ✅ Payé » dès que le paiement est confirmé on-chain. La même UX in-bot que CryptoBot, mais la crypto vous arrive directement, les clés restent les vôtres et la commission est dérisoire.

1. POST /v1/invoices               # votre clé API → { id, pay_address, pay_uri, amount_expected }
2. bot.sendPhoto( https://paygate.love/i/<id>/qr.png )   # QR public, Telegram le récupère lui-même
   + bouton « Ouvrir le portefeuille » → pay_uri
3. notre webhook invoice.paid → bot.editMessage → « ✅ Payé »

L'utilisateur ne quitte jamais le bot du marchand. L'endpoint du QR /i/<id>/qr.png est public (il n'encode que l'adresse). Un exemple copier-coller (grammy/telegraf) se trouve dans docs/BOT-INTEGRATION.md.

Pour les streamers : alertes de dons, barre d'objectif, classement

Tous les endpoints streamer ci-dessous utilisent le token d'alertes — il est déjà intégré dans les URL de l'overlay et du classement sur la page « Alertes » du tableau de bord. C'est une capacité en lecture seule : elle ne remplace jamais votre clé API, mais ne publiez pas l'URL du widget. Sous le capot, un don n'est qu'une facture avec le nom et le message du donateur.

Mettre en place les dons sur votre stream — pas à pas

1. Inscrivez-vous comme streamer : sur la page d'inscription, choisissez le type de compte « Streamer / créateur » — le tableau de bord s'adapte aux dons.
2. Ouvrez Tableau de bord → « Alertes » : vous y trouverez l'URL de l'overlay (/alerts/widget?token=…), les réglages d'apparence des alertes et l'éditeur d'objectif. Copiez l'URL de l'overlay.
3. Dans OBS/Streamlabs : Sources → « + » → Browser Source → collez l'URL, réglez la taille sur votre canevas (p. ex. 1920×1080) → OK. Les alertes et la barre d'objectif s'affichent désormais sur le stream ; vérifiez avec le bouton de don de test.
4. Définissez un objectif de collecte sur la même page « Alertes » — titre, montant cible et devise. La barre de progression apparaît dans l'overlay et via GET /alerts/goal.
5. Créez un lien de don (Tableau de bord → « Liens »), partagez le lien/QR avec vos spectateurs et publiez le classement public /d/<token> sur votre chaîne.
6. Avancé : poussez des dons d'autres plateformes via POST /v1/donations/external, ou alimentez une barre de progression tierce depuis GET /alerts/goal — détails ci-dessous.

Overlay OBS (Browser Source)

Une page HTML prête à l'emploi avec les alertes de dons en direct et la barre d'objectif — ajoutez-la dans OBS/Streamlabs comme Browser Source :

https://paygate.love/alerts/widget?token=<alertToken>

Objectif de collecte — JSON pour n'importe quelle barre de progression (pull)

JSON public de l'objectif en cours (le token fait office d'accès ; cache d'environ 5 s). N'importe quel widget externe de barre de progression peut l'interroger pour afficher le total combiné ailleurs — c'est ainsi qu'on connecte la collecte paygate à une autre barre.

curl "https://paygate.love/alerts/goal?token=<alertToken>"
→ { "active": true, "title": "New PC", "target": 1000,
    "current": 337.5, "currency": "USD" }
# aucun objectif défini → { "active": false }

Dons externes — fusionner d'autres sources dans la barre (push)

Enregistrez un don survenu ailleurs (PayPal, DonationAlerts, manuel) pour qu'il compte dans la MÊME barre d'objectif et, en option, déclenche la même alerte OBS. Une seule barre, toutes les sources — la crypto plus tout ce que vous poussez ici. Authentification : votre clé API.

curl -X POST https://paygate.love/v1/donations/external \
  -H "X-Api-Key: pk_..." -H "Content-Type: application/json" \
  -d '{ "amount": 5, "currency": "USD", "name": "Alice",
        "message": "gg!", "source": "paypal", "fire_alert": true }'
→ 201 { "ok": true, "amount_usd": 5 }

Champs : amount (>0, requis), currency (USD par défaut), name (≤60), message (≤300), source (≤40, "api" par défaut), fire_alert (true par défaut). Le montant est converti en USD pour le total de l'objectif.

Flux d'alertes en direct (SSE)

Des Server-Sent Events à chaque don — construisez un overlay entièrement personnalisé à la place de notre widget :

const es = new EventSource(
  "https://paygate.love/alerts/stream?token=<alertToken>");
es.onmessage = (e) => {
  const d = JSON.parse(e.data); // { name, amount, currency, asset, message }
  showAlert(d);
};

Classement public

Une page publique partageable des meilleurs donateurs (top des soutiens, dons récents, l'objectif) — publiez-la dans la description de votre chaîne ou dans le chat :

https://paygate.love/d/<alertToken>

Versements : par défaut les dons sont custodiaux — retirez depuis le tableau de bord quand vous voulez. Ou ajoutez le xpub de votre portefeuille dans le tableau de bord (non-custodial) et les dons arrivent directement dans votre portefeuille sur EVM / TRON / BTC / LTC / DOGE.

Programme de parrainage

Invitez des boutiques et des streamers et recevez une part de notre commission sur chacun de leurs paiements — à vie. Le taux par défaut est de 20% et il peut être fixé individuellement pour chaque partenaire.

https://paygate.love/?ref=<yourCode>

Votre lien unique se trouve dans Tableau de bord → « Parrainage ». Toute personne qui s'inscrit via ce lien (le code ?ref= est capturé par un cookie, ou saisi dans le champ facultatif du formulaire d'inscription) vous est rattachée définitivement.

Les gains sont crédités automatiquement pour chaque facture confirmée (payée) d'un marchand parrainé, en USD ; les statistiques et les montants se trouvent dans Tableau de bord → « Parrainage ».

💸 Portefeuille prépayé du donateur (dons instantanés)

Un spectateur recharge une fois (la crypto est confirmée une seule fois), puis envoie des dons instantanés à n'importe quel streamer Paygate depuis un solde interne : l'alerte s'affiche aussitôt, sans attente réseau à chaque don. Les dons arrivent dans votre solde habituel ; retirez comme d'habitude. Page du portefeuille : /w (lien au porteur, le token est dans le #fragment, il n'apparaît jamais dans les logs).

🧩 Plugin setup guides

Before you start, grab your API key and secret from your store's Settings page. ⚙️

🛒 WooCommerce — setup

1. Download the plugin zip (the “Download” button on the Plugins page or in your dashboard).
2. WP Admin → Plugins → Add New → Upload Plugin → choose the zip → Install → Activate.
3. WooCommerce → Settings → Payments → enable “Paygate (crypto)” and click Manage.
4. Paste your API key and secret, save. The webhook is wired automatically.
5. Place a test order: pick “Paygate” at checkout, pay, and the order flips to Paid on the signed webhook.

🖥️ WHMCS — setup

1. Download and unzip. Inside you'll find a modules/gateways/ folder.
2. Upload the contents of modules/gateways/ into your WHMCS root (it merges with the existing structure).
3. WHMCS Admin → Setup → Payments → Payment Gateways → “All Payment Gateways” tab → activate “Paygate”.
4. Enter your API key and secret, save. Verify with a test invoice — status updates via the callback.

🛍️ OpenCart — setup

1. Download the zip. Copy the contents of upload/ into your OpenCart root (merges with admin/ and catalog/), or install the zip via Extensions → Installer.
2. Extensions → Extensions → Payments → find “Paygate — Crypto Payments” → “+” (Install) → pencil (Edit).
3. Status = Enabled, paste your API key and secret, pick the order statuses, save. The webhook is wired automatically (callback_url).
4. Test order: pick “Pay with Crypto” at checkout, pay, and the status updates via the signed webhook.

🧿 PrestaShop — setup

1. Download the module zip. Back office → Modules → Module Manager → “Upload a module” → choose the zip → install.
2. Click “Configure”, paste your API key and secret (leave base URL as https://paygate.love), save.
3. The webhook is wired automatically (callback_url) and shown on the settings page.
4. Test order: pick “Pay with Crypto”, pay, and the order moves to “Payment accepted” on the signed webhook.

🅜 Magento 2 — setup

1. Copy the Paygate folder into app/code/ (module lives at app/code/Paygate/Crypto).
2. From the Magento root: bin/magento module:enable Paygate_Crypto && bin/magento setup:upgrade && setup:di:compile && cache:flush.
3. Admin → Stores → Configuration → Sales → Payment Methods → “Paygate — Crypto Payments”: Enabled = Yes, paste your API key and secret, save.
4. Webhook: https://your-store/paygate/webhook (sent automatically as callback_url). Verify with a test order.

🛒 CS-Cart — setup

1. Download the zip. Administration → Add-ons → Manage add-ons → “+” (Upload & install) → choose the zip.
2. Administration → Payment methods → Add: Processor = “Paygate (crypto)”.
3. On the Configure tab paste your API key and secret (leave base URL as https://paygate.love), save and activate.
4. The webhook is wired automatically (callback_url). Verify with a test order — the status updates via the signed webhook.

🅱️ Blesta — setup

1. Download the zip. Copy components/gateways/nonmerchant/paygate/ into your Blesta install at the same path.
2. Settings → Company → Payment Gateways → Available → install “Paygate — Crypto Payments”.
3. Click “Manage”, enter your API key and secret (leave base URL as https://paygate.love), save.
4. The callback URL is Blesta's standard gateway callback, sent automatically. Verify with a test invoice.

🧾 FOSSBilling — setup

1. Download the zip and extract library/Payment/Adapter/Paygate.php into your FOSSBilling root (paths merge).
2. Admin → System → Payment gateways → New payment gateway → activate “Paygate”.
3. Paste your API key and secret (leave base URL as https://paygate.love), save.
4. The webhook (IPN) is wired automatically as callback_url. Verify with a test invoice — payment applies via the signed webhook.

💬 XenForo — setup

1. Download the zip and copy the contents of upload/ into your forum root (creates src/addons/Paygate/Crypto).
2. Admin → Add-ons → install “Paygate — Crypto Payments”.
3. Admin → Setup → Payment profiles → Add payment profile → Paygate: paste your API key and secret, save.
4. Attach the profile to your User upgrades. Payment confirms via the signed webhook through payment_callback.php.

📦 BoxBilling — setup

1. Download the zip and extract bb-library/Payment/Adapter/Paygate.php into your BoxBilling root.
2. Admin → Configuration → Payment gateways → New payment gateway → activate “Paygate”.
3. Paste your API key and secret (base URL https://paygate.love), save. The webhook (IPN) wires automatically.
4. Verify with a test invoice — payment applies via the signed webhook.

🎮 Paymenter — setup

1. Download the zip and extract extensions/Gateways/Paygate into your Paymenter root.
2. Admin → Extensions → Gateways → enable “Paygate”.
3. Paste your API key and secret (base URL https://paygate.love), save.
4. Webhook: /extensions/gateways/paygate/webhook (sent automatically as callback_url). Verify with a test invoice.

👥 Invision Community — setup

1. Download the zip and install the paygate application (AdminCP → System → Applications; see README for dev-mode / tar build).
2. AdminCP → Commerce → Payments → Payment Methods → Create New → Paygate.
3. Paste your API key and secret (base URL https://paygate.love), save.
4. Payment confirms via the signed webhook; underpaid goes to Held for manual review.

📋 vBulletin — setup (vB4 / vB5)

1. Pick your archive: vB4 (4.2.x) → includes/paymentapi/class_paygate.php; vB5 → core/includes/paymentapi/class_paygate.php.
2. Copy the class file to the right path and run install.sql from the archive (registers the method in the paymentapi table).
3. AdminCP → Paid Subscriptions → Payment API Manager → Paygate: enable, paste your API key and secret (base URL https://paygate.love).
4. The subscription activates via the signed webhook (payment_gateway.php); duplicates bounce on the transaction id.

🎮 Azuriom — setup

1. Download the zip and add PaygateMethod to the Shop plugin (see README: patch PaymentManager or register via registerPaymentMethod).
2. Admin → Shop → Settings → Payment gateways → Paygate: paste your API key and secret (base URL https://paygate.love).
3. Payment confirms via the signed webhook (shop.payments.notification); completed payments are idempotent.

🏬 Webasyst / Shop-Script — setup

1. Download the zip and extract wa-plugins/payment/paygate into your Webasyst root.
2. Store → Settings → Payment → add method → Paygate: paste your API key and secret (base URL https://paygate.love).
3. Payment confirms via the signed webhook (waPayment relay URL); dedup via native_id.

🛒 X-Cart — setup

1. Download the zip and extract classes/ and skins/ into your X-Cart root, then rebuild the cache (Re-deploy).
2. Admin → Store setup → Payment methods → enable “Paygate”.
3. Paste your API key and secret (base URL https://paygate.love), save. Payment confirms via the signed webhook.

🛍️ Zen Cart — setup

1. Download the zip: module file to includes/modules/payment/, language to includes/languages/english/modules/payment/, and ipn_paygate.php to the store root.
2. Admin → Modules → Payment → Paygate → Install; paste your API key and secret (base URL https://paygate.love).
3. The order is created as pending; status updates via the signed webhook (ipn_paygate.php).

🏪 osCommerce — setup

1. Download the zip (targets osCommerce 2.3.x): module file to includes/modules/payment/, callback.php to ext/modules/payment/paygate/, language to includes/languages/english/….
2. Admin → Modules → Payment → Paygate → Install; paste your API key and secret (base URL https://paygate.love).
3. Order status updates via the signed webhook (ext/…/callback.php); the webhook retries until the order is found.

🛒 VirtueMart (Joomla) — setup

1. Joomla → Extensions → Install: upload the zip (or copy to plugins/vmpayment/paygate/ and click Discover).
2. Enable the “VM Payment - Paygate” plugin, then VirtueMart → Payment Methods → create a method using it.
3. Paste your API key and secret (base URL https://paygate.love), save. Payment confirms via the signed webhook.

💧 Drupal Commerce — setup

1. Extract the module to modules/custom/paygate (or via composer), enable it on Extend.
2. Commerce → Configuration → Payment gateways → Add: choose Paygate (off-site redirect).
3. Paste your API key and secret (base URL https://paygate.love), save. The notify webhook is the source of truth.

⬇️ Easy Digital Downloads — setup

1. WP Admin → Plugins → Add New → Upload → choose the zip → Install → Activate.
2. Downloads → Settings → Payment Gateways → enable “Paygate” and open its settings.
3. Paste your API key and secret (base URL https://paygate.love), save. Payment confirms via the signed webhook (edd-listener).

🧾 HostBill — setup (free bridge)

1. This is a lightweight bridge, not the paid SDK module: unzip it into a web-accessible folder, e.g. https://your-billing/paygate/.
2. HostBill → Settings → API: create an API user, whitelist this server's IP. Copy config.sample.php → config.php and fill in the HostBill + Paygate keys and a random link_secret.
3. In your Paygate store settings set the webhook/callback → https://your-billing/paygate/callback.php. A payment closes the invoice automatically via the Admin API (addInvoicePayment).
4. Add the “Pay with Crypto” button to invoices via the hooks/paygate_button.php hook (into includes/hooks/) or a ready signed link pay.php?invoice_id=…&token=… — see the README.

🖥️ WISECP — setup

1. Copy the coremio/ folder from the zip over your WISECP root (the module lands in coremio/modules/Payment/Paygate/).
2. Admin → Settings → Payment Gateways → enable “Paygate — Crypto Payments” and paste your API key and secret (base URL https://paygate.love).
3. No webhook setup needed: the module passes its callback link with every checkout. Payment confirms via the signed webhook.

🧾 ClientExec — setup

1. Unzip the archive into plugins/gateways/paygate/ of your ClientExec install.
2. Settings → Plugins → Payment Processors → activate Paygate and paste your API key and secret (base URL https://paygate.love).
3. Webhook: https://your-domain/plugins/gateways/paygate/callback.php — set it in your Paygate store settings.

🎨 Tilda — setup (universal payment system)

1. This is a self-hosted bridge: unzip it onto your PHP hosting (e.g. https://your-domain/paygate/) and fill in config.php from the sample.
2. In Tilda: Site Settings → Payment Systems → Universal payment system → API URL = https://your-domain/paygate/receive.php; field mapping and signature per the README.
3. Paygate webhook: https://your-domain/paygate/callback.php. On payment the bridge sends Tilda a signed notification — the order flips to paid.

🛒 BigCommerce — setup (bridge)

1. BigCommerce's native payment list is partner-gated, so this is a bridge: unzip onto your PHP hosting and fill in config.php.
2. In BigCommerce create a store-level API account (Orders scope), enable the offline method “Cryptocurrency (Paygate)” and add the pay button per the README (Script Manager).
3. Paygate webhook: https://your-domain/paygate/callback.php — on payment the order moves to Awaiting Fulfillment automatically.

🛍️ Zid — setup (private bridge)

1. Zid's App Store won't list crypto (SAMA), so the bridge runs privately with your own partner credentials. Deploy the Node service from the zip (npm i && npm run build).
2. Fill in .env (Zid tokens, Paygate keys) and register the order-created webhook per the README.
3. The buyer pays via the /pay/:orderId link; on confirmation the bridge marks the order paid through the Zid API.

1. Créer une facture

POST /v1/invoices
X-Api-Key: pk_...
Idempotency-Key: order-1042        # facultatif, évite les doublons
Content-Type: application/json

{ "network": "ton", "asset": "USDT", "amount": "25.00", "order_id": "1042" }

La réponse contient id, pay_address, pay_uri, expires_at. Dirigez l'acheteur vers /pay/.

Champs de requête facultatifs : quote_currency (devise du montant, USD par défaut), order_id, callback_url (webhook propre à la facture), success_url (où renvoyer l'acheteur), test (sandbox). La réponse complète inclut aussi status, network, asset, amount_expected, rate_locked, fee_percent, telegram_url.

Bac à sable : ajoutez "test": true — la facture n'est pas suivie sur la blockchain et n'affecte jamais votre solde ; simulez son paiement dans le tableau de bord pour valider vos webhooks. Son webhook est signé à l'identique mais contient "test": true — n'exécutez les commandes que lorsque test === false.

1b. Live rate — price a USD amount in BTC/LTC

GET /v1/quote?asset=BTC&quote_currency=USD
X-Api-Key: pk_...
→ { "asset": "BTC", "quote_currency": "USD", "rate": "63022.25" }

# price a $12.99 item in BTC:
#   amount = 12.99 / 63022.25 = 0.00020612  → send as "amount" to /v1/invoices
# optional: pass &amount=12.99 to get "quote_amount" back too

The amount is denominated in quote_currency (default USD) — the gateway converts it to the coin at the live rate, no manual math needed. For USDT/USDC quoted in USD that's 1:1. To price directly in the coin, set quote_currency to the coin symbol (e.g. quote_currency=BTC) — then no conversion happens. The rate comes from CoinGecko/Coinbase, refreshes every ~45s and is locked into the invoice (rate_locked), so the buyer always pays the correct up-to-the-minute amount. The response returns quote_amount (as you sent it) and amount_expected (the final coin amount).

Don't want to do the math? Use POST /v1/checkouts with a USD amount — the buyer picks the coin and we handle the live conversion.

Lien de paiement (l'acheteur choisit la monnaie)

POST /v1/checkouts
X-Api-Key: pk_...
Content-Type: application/json

{ "amount": "25.00", "quote_currency": "USD", "order_id": "1042" }
→ { "checkout_url": "https://…/checkout/…", "short_url": "https://…/c/…",
    "telegram_url": "https://t.me/…", "expires_at": "…" }

POST /v1/checkouts avec un montant crée un lien où l'acheteur choisit le réseau et la monnaie — idéal sans intégration. Réponse : checkout_url, short_url, telegram_url, expires_at. Prend en charge les mêmes order_id, callback_url et success_url que les factures.

🤖 Accepter des paiements dans un bot / une boutique Telegram

Vous vendez directement dans Telegram ? Pas besoin de site web. Votre bot crée un paiement via l'API et reçoit un telegram_url — un lien profond qui ouvre le parcours de paiement dans notre bot Telegram : l'acheteur choisit une monnaie/un réseau, voit l'adresse et le QR, puis paie. Vous recevez un webhook signé et livrez la marchandise.

1. L'acheteur appuie sur « Acheter » dans votre bot → votre bot appelle POST /v1/checkouts (avec order_id et callback_url).
2. Votre bot répond avec un bouton inline pointant vers telegram_url (ou short_url pour payer sur une page web).
3. L'acheteur paie sans quitter Telegram → vous recevez le webhook invoice.paid → votre bot livre le produit/l'accès.

// Telegram bot (grammY/Telegraf) — sell for crypto
bot.callbackQuery("buy", async (ctx) => {
  const r = await fetch("https://paygate.love/v1/checkouts", {
    method: "POST",
    headers: { "X-Api-Key": PK, "Content-Type": "application/json" },
    body: JSON.stringify({ amount: "9.99", quote_currency: "USD",
      order_id: ctx.from.id + ":" + Date.now(),
      callback_url: "https://my-bot.example/paygate-webhook" }),
  }).then((x) => x.json());
  // r.telegram_url opens the pay flow INSIDE Telegram (coin choice + address + QR)
  await ctx.reply("Оплатить криптой:", {
    reply_markup: { inline_keyboard: [[{ text: "💳 Pay", url: r.telegram_url }]] },
  });
});

// Deliver the goods on the signed webhook (see "Webhooks" below)
app.post("/paygate-webhook", (req, res) => {
  if (verifySignature(req) && req.body.event === "invoice.paid" && !req.body.test)
    deliverOrder(req.body.order_id);   // ship / grant access
  res.sendStatus(200);
});

Conseil : utilisez telegram_url pour payer dans Telegram, ou short_url pour une page de paiement web classique. Liez order_id à l'acheteur (chat id) et à la commande afin que le webhook corresponde sans ambiguïté. Ne livrez jamais la marchandise tant que test n'est pas false.

2. Statut de la facture

GET /v1/invoices/<id>
X-Api-Key: pk_...
→ { "status": "paid", "amount_received": "25",
    "settlement": { "gross": "25", "fee": "…", "spread": "…", "net": "…", "revenue": "…" } }

Statuts : pending → detected → paid (ainsi que underpaid, overpaid, expired, cancelled, settled).

Autres endpoints

GET /v1/invoices — liste des factures avec pagination (limit jusqu'à 200, offset, filtre par status).
POST /v1/invoices/<id>/cancel — annuler une facture pending/detected (déclenche invoice.cancelled).
GET /v1/quote?asset=&quote_currency=&amount= — aperçu du taux et du montant converti.
GET /v1/networks — liste des réseaux et des monnaies (aucune clé requise).
GET /v1/reconciliation?from=&to= — rapprochement facturé vs reçu (limite 30 req/min).

Rapprochement : GET /v1/reconciliation?from=&to= — montants facturés vs reçus (nets de commissions) + écarts par commande (sous-payées, surpayées, impayées). Nous sommes la source de vérité pour ce qui a été reçu ; en mode non-custodial, rapprochez avec votre propre portefeuille. L'outil fournit les données — les décisions (expédition, litiges) vous appartiennent.

3. Webhook

À chaque changement de statut, nous envoyons un POST à l'URL de votre webhook. En-tête X-Signature = HMAC-SHA256(body, api_secret). Vérifiez la signature et la fraîcheur (timestamp) avant traitement.

Charge utile du webhook

{
  "event": "invoice.paid",
  "invoice_id": "inv_…", "order_id": "1042",
  "status": "paid", "test": false,
  "asset": "USDT", "network": "ton",
  "quote_currency": "USD",
  "amount_expected": "25", "amount_received": "25",
  "tx_hash": "…", "timestamp": "2026-07-12T20:00:00.000Z",
  "invoice": { "id": "inv_…", "order_id": "1042", "status": "paid",
               "quote_currency": "USD",
               "amount_expected": "25", "amount_received": "25" }
}

Événements : invoice.detected, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.cancelled. En-têtes : X-Signature, X-Webhook-Id, X-Event.

// Node — verify signature (constant-time), dedupe, gate on test
import crypto from "node:crypto";
const expected = crypto.createHmac("sha256", API_SECRET).update(rawBody).digest("hex");
const sig = String(req.headers["x-signature"] ?? "");
if (sig.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
  return res.sendStatus(401);
const evt = JSON.parse(rawBody);
if (Date.now() - new Date(evt.timestamp) > 5*60_000) return res.sendStatus(400); // anti-replay
if (seen(req.headers["x-webhook-id"])) return res.sendStatus(200);               // idempotency
if (evt.event === "invoice.paid" && evt.test === false) fulfil(evt.order_id);   // only real payments

Livraison : 3 tentatives rapides, puis une file durable jusqu'à 12 tentatives avec backoff jusqu'à 1 h. Dédupliquez via X-Webhook-Id. L'URL du webhook doit être publique en http(s) — les hôtes localhost/privés et les redirections sont rejetés. Ne livrez jamais tant que test n'est pas false.

Renforcement

• Idempotency-Key à la création de facture — les nouvelles tentatives ne créent pas de doublons.
• Limite de débit : 120 requêtes/min par adresse IP.
• Webhook : X-Signature (HMAC), X-Webhook-Id (idempotence), timestamp (anti-rejeu).