Documentación de la API

Flujo: crea una factura → envía al cliente a la página de pago → recibe un webhook firmado. Prefijo /v1. Autenticación mediante la cabecera X-Api-Key.

Especificación OpenAPI 3 (JSON) Obtener claves

Redes compatibles

Migra desde otro procesador — sin reescribir código

¿Ya integraste Cryptomus / NOWPayments / Coinbase Commerce? Cambia en tu SDK solo la base-URL y la clave — aceptamos su formato de create-invoice, devolvemos nuestra página de pago en su formato de respuesta y enviamos el webhook en su esquema firmado, así tu código de verificación funciona tal cual. Correlación por order_id.

# antes:  https://api.cryptomus.com/v1/payment
# después:  https://paygate.love/compat/cryptomus/v1/payment
# clave: tu clave API de paygate; el secreto del webhook = tu apiSecret de paygate

¿Necesitas otro procesador? Escríbenos y añadimos el adaptador (es un solo módulo).

Acepta pagos dentro de tu propio bot de Telegram

¿Tu comercio es un bot? No mandes al usuario a una web ni a un bot-monedero ajeno. Tu bot llama a nuestra API, muestra la dirección + el importe + el QR directamente en el chat y cambia el mensaje a «✅ Pagado» en cuanto el pago se confirma en la cadena. El mismo UX in-bot que CryptoBot, pero la cripto te llega directamente, las claves son tuyas y la comisión es mínima.

1. POST /v1/invoices               # tu clave API → { id, pay_address, pay_uri, amount_expected }
2. bot.sendPhoto( https://paygate.love/i/<id>/qr.png )   # QR público, Telegram lo descarga solo
   + botón «Abrir monedero» → pay_uri
3. nuestro webhook invoice.paid → bot.editMessage → «✅ Pagado»

El usuario nunca sale del bot del comercio. El endpoint del QR /i/<id>/qr.png es público (solo codifica la dirección). Hay un ejemplo copy-paste (grammy/telegraf) en docs/BOT-INTEGRATION.md.

Para streamers: alertas de donaciones, barra de meta, ranking

Todos los endpoints de streamer de abajo usan el token de alertas — ya viene incrustado en las URLs del overlay y del ranking en la página «Alertas» del panel. Es una capacidad de solo lectura: nunca sustituye tu clave API, pero no publiques la URL del widget. Por dentro, una donación es simplemente una factura con el nombre y el mensaje del donante.

Cómo montar las donaciones en tu stream — paso a paso

1. Regístrate como streamer: en la página de registro elige el tipo de cuenta «Streamer / creador» — el panel se adapta a las propinas.
2. Abre Panel → «Alertas»: ahí están la URL del overlay (/alerts/widget?token=…), los ajustes de apariencia de las alertas y el editor de la meta. Copia la URL del overlay.
3. En OBS/Streamlabs: Sources → «+» → Browser Source → pega la URL, ajusta el tamaño a tu lienzo (p. ej. 1920×1080) → OK. Las alertas y la barra de meta ya se muestran en el stream; compruébalo con el botón de donación de prueba.
4. Configura una meta de recaudación en la misma página «Alertas» — título, importe objetivo y moneda. La barra de progreso aparece en el overlay y vía GET /alerts/goal.
5. Crea un enlace de donación (Panel → «Enlaces»), comparte el enlace/QR con tus espectadores y publica el ranking público /d/<token> en tu canal.
6. Avanzado: empuja donaciones de otras plataformas vía POST /v1/donations/external, o alimenta una barra de progreso de terceros desde GET /alerts/goal — detalles abajo.

Overlay para OBS (Browser Source)

Una página HTML lista con alertas de donaciones en vivo y la barra de meta — añádela a OBS/Streamlabs como Browser Source:

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

Meta de recaudación — JSON para cualquier barra de progreso (pull)

JSON público de la meta actual (el token es la capacidad; caché de ~5 s). Cualquier widget externo de barra de progreso puede consultarlo para mostrar el total combinado en otro sitio — así conectas la recaudación de paygate a otra barra.

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

Donaciones externas — fusiona otras fuentes en la barra (push)

Registra una donación ocurrida en otro sitio (PayPal, DonationAlerts, manual) para que cuente en la MISMA barra de meta y, opcionalmente, dispare la misma alerta de OBS. Una barra, todas las fuentes — cripto más lo que empujes aquí. Autenticación: tu clave 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 }

Campos: amount (>0, obligatorio), currency (por defecto USD), name (≤60), message (≤300), source (≤40, por defecto "api"), fire_alert (por defecto true). El importe se convierte a USD para el total de la meta.

Flujo de alertas en vivo (SSE)

Server-Sent Events con cada donación — construye un overlay totalmente personalizado en lugar de nuestro 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);
};

Ranking público

Una página pública compartible con los mejores donantes (top de mecenas, donaciones recientes, la meta) — publícala en la descripción de tu canal o en el chat:

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

Pagos: por defecto las donaciones son custodiadas — retira desde el panel cuando quieras. O añade el xpub de tu monedero en el panel (non-custodial) y las donaciones llegan directas a tu monedero en EVM / TRON / BTC / LTC / DOGE.

Programa de referidos

Invita a tiendas y streamers y gana una parte de nuestra comisión de cada pago que hagan — de por vida. La tasa por defecto es del 20% y puede fijarse individualmente para cada socio.

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

Tu enlace único está en Panel → «Referidos». Quien se registre a través de él (el código ?ref= se captura mediante una cookie, o se introduce en el campo opcional del formulario de registro) queda vinculado a ti para siempre.

Las comisiones se acreditan automáticamente por cada factura confirmada (pagada) del comercio referido, en USD; las estadísticas y los importes están en Panel → «Referidos».

💸 Monedero prepago del donante (donaciones instantáneas)

Un espectador recarga una vez (el crypto se confirma una sola vez) y luego lanza donaciones instantáneas a cualquier streamer de Paygate desde un saldo interno: la alerta aparece de inmediato, sin esperar a la red en cada donación. Las donaciones llegan a tu saldo normal; retíralas como siempre. Página del monedero: /w (enlace al portador, el token va en el #fragment, nunca aparece en los 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. Crear una factura

POST /v1/invoices
X-Api-Key: pk_...
Idempotency-Key: order-1042        # opcional, evita duplicados
Content-Type: application/json

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

La respuesta incluye id, pay_address, pay_uri, expires_at. Envía al comprador a /pay/.

Campos opcionales de la solicitud: quote_currency (moneda del importe, por defecto USD), order_id, callback_url (webhook por factura), success_url (adónde devolver al comprador), test (sandbox). La respuesta completa también incluye status, network, asset, amount_expected, rate_locked, fee_percent, telegram_url.

Sandbox: añade "test": true — la factura no se monitorea en la blockchain y nunca afecta tu saldo; simula su pago en el panel para validar los webhooks. Su webhook se firma de forma idéntica pero incluye "test": true — entrega los pedidos solo cuando 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.

Enlace de pago (el comprador elige la moneda)

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 con un importe crea un enlace donde el comprador elige la red y la moneda — ideal sin integración. Respuesta: checkout_url, short_url, telegram_url, expires_at. Admite los mismos order_id, callback_url y success_url que las facturas.

🤖 Acepta pagos en un bot / tienda de Telegram

¿Vendes directamente en Telegram? No necesitas sitio web. Tu bot crea un checkout mediante la API y recibe un telegram_url — un deep link que abre el flujo de pago dentro de nuestro bot de Telegram: el comprador elige la moneda/red, ve la dirección y el QR, y paga. Tú recibes un webhook firmado y entregas el producto.

1. El comprador pulsa “Comprar” en tu bot → tu bot llama a POST /v1/checkouts (con order_id y callback_url).
2. Tu bot responde con un botón inline que enlaza a telegram_url (o short_url para pagar en una página web).
3. El comprador paga sin salir de Telegram → recibes el webhook invoice.paid → tu bot entrega el producto/acceso.

// 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);
});

Consejo: usa telegram_url para pagar dentro de Telegram, o short_url para una página web de pago normal. Vincula order_id al comprador (chat id) y al pedido para que el webhook se asocie sin ambigüedad. Nunca entregues el producto mientras test no sea false.

2. Estado de la factura

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

Estados: pending → detected → paid (además de underpaid, overpaid, expired, cancelled, settled).

Más endpoints

GET /v1/invoices — lista de facturas con paginación (limit hasta 200, offset, filtro por status).
POST /v1/invoices/<id>/cancel — cancelar una factura pending/detected (emite invoice.cancelled).
GET /v1/quote?asset=&quote_currency=&amount= — previsualizar el tipo de cambio y el importe convertido.
GET /v1/networks — lista de redes y monedas (no requiere clave).
GET /v1/reconciliation?from=&to= — conciliación facturado vs recibido (límite 30 solicitudes/min).

Conciliación: GET /v1/reconciliation?from=&to= — facturado vs recibido (neto de comisiones) + discrepancias por pedido (pagos insuficientes, en exceso, impagados). Somos la fuente de verdad sobre lo que llegó; para non-custodial, concilia contra tu propio monedero. La herramienta proporciona datos — las decisiones (envíos, disputas) son tuyas.

3. Webhook

Al cambiar el estado hacemos POST a la URL de tu webhook. Cabecera X-Signature = HMAC-SHA256(body, api_secret). Verifica la firma y la vigencia (timestamp) antes de procesar.

Payload del 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" }
}

Eventos: invoice.detected, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.cancelled. Cabeceras: 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

Entrega: 3 intentos rápidos y luego una cola persistente de hasta 12 intentos con backoff de hasta 1 h. Deduplica por X-Webhook-Id. La URL del webhook debe ser http(s) pública — se rechazan localhost/hosts privados y las redirecciones. Nunca entregues el pedido mientras test no sea false.

Reforzamiento

• Idempotency-Key al crear la factura: los reintentos no crean duplicados.
• Límite de tasa: 120 solicitudes/min por dirección IP.
• Webhook: X-Signature (HMAC), X-Webhook-Id (idempotencia), timestamp (anti-replay).