Documentação da API

Fluxo: crie uma fatura → envie o cliente à página de pagamento → receba um webhook assinado. Prefixo /v1. Autenticação pelo cabeçalho X-Api-Key.

Especificação OpenAPI 3 (JSON) Obter chaves

Redes suportadas

Migre de outro processador — sem reescrever código

Já integrado com Cryptomus / NOWPayments / Coinbase Commerce? Troque no SDK apenas a base-URL e a chave — aceitamos o formato de create-invoice deles, devolvemos a nossa página de pagamento no formato de resposta deles e enviamos o webhook no esquema assinado deles, então o seu código de verificação funciona como está. Correlação por order_id.

# antes:  https://api.cryptomus.com/v1/payment
# depois:  https://paygate.love/compat/cryptomus/v1/payment
# chave: sua chave de API do paygate; segredo do webhook = seu apiSecret do paygate

Precisa de outro processador? Escreva para nós — adicionamos o adaptador (é um único módulo).

Aceite pagamentos dentro do seu próprio bot no Telegram

Seu negócio é um bot? Não mande o usuário para um site nem para um bot-carteira de terceiros. Seu bot chama a nossa API, mostra o endereço + valor + QR direto no chat e troca a mensagem para «✅ Pago» assim que o pagamento é confirmado na rede. O mesmo UX in-bot do CryptoBot, mas a cripto vai direto para você, as chaves são suas e a taxa é mínima.

1. POST /v1/invoices               # sua chave de API → { id, pay_address, pay_uri, amount_expected }
2. bot.sendPhoto( https://paygate.love/i/<id>/qr.png )   # QR público, o próprio Telegram faz o fetch
   + botão «Abrir carteira» → pay_uri
3. nosso webhook invoice.paid → bot.editMessage → «✅ Pago»

O usuário nunca sai do bot do lojista. O endpoint do QR /i/<id>/qr.png é público (codifica só o endereço). Um exemplo copy-paste pronto (grammy/telegraf) está em docs/BOT-INTEGRATION.md.

Para streamers: alertas de doações, barra de meta, ranking

Todos os endpoints de streamer abaixo usam o token de alertas — ele já vem embutido nas URLs do overlay e do ranking na página «Alertas» do painel. É uma capacidade somente leitura: nunca substitui sua chave de API, mas não publique a URL do widget. Por baixo dos panos, uma doação é apenas uma fatura com o nome e a mensagem do doador.

Como configurar doações na sua stream — passo a passo

1. Registre-se como streamer: na página de cadastro escolha o tipo de conta «Streamer / criador» — o painel se adapta às doações.
2. Abra Painel → «Alertas»: lá estão a URL do overlay (/alerts/widget?token=…), as configurações de aparência dos alertas e o editor da meta. Copie a URL do overlay.
3. No OBS/Streamlabs: Sources → «+» → Browser Source → cole a URL, ajuste o tamanho ao seu canvas (ex.: 1920×1080) → OK. Os alertas e a barra de meta agora aparecem na stream; teste com o botão de doação de teste.
4. Defina uma meta de arrecadação na mesma página «Alertas» — título, valor alvo e moeda. A barra de progresso aparece no overlay e via GET /alerts/goal.
5. Crie um link de doação (Painel → «Links»), compartilhe o link/QR com os espectadores e publique o ranking público /d/<token> no seu canal.
6. Avançado: envie doações de outras plataformas via POST /v1/donations/external, ou alimente uma barra de progresso de terceiros a partir de GET /alerts/goal — detalhes abaixo.

Overlay para OBS (Browser Source)

Uma página HTML pronta com alertas de doações ao vivo e a barra de meta — adicione-a ao OBS/Streamlabs como Browser Source:

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

Meta de arrecadação — JSON para qualquer barra de progresso (pull)

JSON público da meta atual (o token é a capacidade; cache de ~5 s). Qualquer widget externo de barra de progresso pode consultá-lo para exibir o total combinado em outro lugar — é assim que você conecta a arrecadação do paygate a outra barra.

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

Doações externas — junte outras fontes na barra (push)

Registre uma doação feita em outro lugar (PayPal, DonationAlerts, manual) para que ela conte na MESMA barra de meta e, opcionalmente, dispare o mesmo alerta no OBS. Uma barra, todas as fontes — cripto mais o que você enviar aqui. Autenticação: sua chave de 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, obrigatório), currency (padrão USD), name (≤60), message (≤300), source (≤40, padrão "api"), fire_alert (padrão true). O valor é convertido para USD no total da meta.

Fluxo de alertas ao vivo (SSE)

Server-Sent Events a cada doação — monte um overlay totalmente personalizado em vez do nosso 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

Uma página pública compartilhável com os maiores doadores (top apoiadores, doações recentes, a meta) — publique-a na descrição do canal ou no chat:

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

Pagamentos: por padrão as doações são custodiais — saque pelo painel quando quiser. Ou adicione o xpub da sua carteira no painel (non-custodial) e as doações caem direto na sua carteira em EVM / TRON / BTC / LTC / DOGE.

Programa de indicações

Convide lojas e streamers e ganhe uma parte da nossa taxa em cada pagamento que eles fizerem — para sempre. A porcentagem padrão é de 20% e pode ser definida individualmente para cada parceiro.

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

Seu link único está em Painel → «Indicações». Quem se registrar por ele (o código ?ref= é capturado via cookie, ou informado no campo opcional do formulário de registro) fica vinculado a você para sempre.

As comissões são creditadas automaticamente a cada fatura confirmada (paga) do lojista indicado, em USD; as estatísticas e os valores ficam em Painel → «Indicações».

💸 Carteira pré-paga do doador (doações instantâneas)

Um espectador recarrega uma vez (o crypto confirma uma única vez) e depois dispara doações instantâneas para qualquer streamer do Paygate a partir de um saldo interno — o alerta aparece na hora, sem espera de rede a cada doação. As doações caem no seu saldo normal; saque como de costume. Página da carteira: /w (link ao portador, o token vai no #fragment, nunca aparece nos 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. Criar uma fatura

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

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

A resposta traz id, pay_address, pay_uri, expires_at. Envie o comprador para /pay/.

Campos opcionais da requisição: quote_currency (moeda do valor, padrão USD), order_id, callback_url (webhook por fatura), success_url (para onde retornar o comprador), test (sandbox). A resposta completa também inclui status, network, asset, amount_expected, rate_locked, fee_percent, telegram_url.

Sandbox: adicione "test": true — a fatura não é monitorada na blockchain e nunca afeta seu saldo; simule o pagamento no painel para validar os webhooks. O webhook dela é assinado da mesma forma, mas carrega "test": true — só libere pedidos quando 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.

Link de pagamento (o comprador escolhe a moeda)

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 com um valor cria um link em que o comprador escolhe a rede e a moeda — ideal quando não há integração. Resposta: checkout_url, short_url, telegram_url, expires_at. Suporta os mesmos order_id, callback_url e success_url das faturas.

🤖 Aceite pagamentos em um bot / loja do Telegram

Vende diretamente no Telegram? Não precisa de site. Seu bot cria um checkout pela API e recebe um telegram_url — um deep link que abre o fluxo de pagamento dentro do nosso bot do Telegram: o comprador escolhe a moeda/rede, vê o endereço e o QR e paga. Você recebe um webhook assinado e entrega o produto.

1. O comprador toca em “Comprar” no seu bot → seu bot chama POST /v1/checkouts (com order_id e callback_url).
2. Seu bot responde com um botão inline apontando para o telegram_url (ou short_url para pagar em uma página web).
3. O comprador paga sem sair do Telegram → você recebe o webhook invoice.paid → seu bot entrega o produto/acesso.

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

Dica: use telegram_url para pagar dentro do Telegram, ou short_url para uma página web de checkout comum. Vincule o order_id ao comprador (chat id) e ao pedido para que o webhook seja mapeado sem ambiguidade. Nunca entregue o produto enquanto test não for false.

2. Status da fatura

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

Status: pending → detected → paid (além de underpaid, overpaid, expired, cancelled, settled).

Mais endpoints

GET /v1/invoices — lista as faturas com paginação (limit até 200, offset, filtro por status).
POST /v1/invoices/<id>/cancel — cancela uma fatura pending/detected (dispara invoice.cancelled).
GET /v1/quote?asset=&quote_currency=&amount= — pré-visualiza a taxa e o valor convertido.
GET /v1/networks — lista redes e moedas (sem necessidade de chave).
GET /v1/reconciliation?from=&to= — conciliação faturado vs. recebido (limite de 30 req/min).

Conciliação: GET /v1/reconciliation?from=&to= — faturado vs recebido (líquido de taxas) + divergências por pedido (pagamentos a menor/a maior, não pagos). Somos a fonte de verdade sobre o que chegou; no modo non-custodial, concilie com a sua própria carteira. A ferramenta fornece os dados — as decisões (envio, disputas) são suas.

3. Webhook

A cada mudança de status enviamos um POST para a URL do seu webhook. Cabeçalho X-Signature = HMAC-SHA256(body, api_secret). Verifique a assinatura e a validade (timestamp) antes de processar.

Payload do 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. Cabeçalhos: 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 tentativas rápidas e, em seguida, uma fila durável com até 12 tentativas com backoff de até 1h. Deduplique por X-Webhook-Id. A URL do webhook deve ser http(s) pública — localhost/hosts privados e redirecionamentos são rejeitados. Nunca libere o pedido enquanto test não for false.

Reforço de segurança

• Idempotency-Key na criação da fatura — retentativas não geram duplicidades.
• Limite de taxa: 120 requisições/min por endereço IP.
• Webhook: X-Signature (HMAC), X-Webhook-Id (idempotência), timestamp (anti-replay).