PayX API & webhook docs

PayX is a non-custodial payment tracker. The server never holds private keys — it only watches the chain on your behalf, matches inbound transfers to invoices you create, and notifies your handler via signed webhooks. In managed mode funds land at addresses derived from your xpub; in monitored mode they land at the single address you provided. Either way PayX never holds the keys.

This page covers what's already shipped: the concepts, the API surface, and the webhook protocol. If you're integrating for the first time, read Quick start and the Concepts section before the API reference — the API field names assume the vocabulary from there.

Quick start

1. Sign up at payx.lol/register and confirm the email code.
2. Open Methods and add a payment method (xpub for managed mode, single address for monitored).
3. Generate an API key under Settings → API keys. The full key is shown once; store it.
4. Configure your webhook URL on Settings → Webhooks. The secret is auto-generated — reveal and copy it into your handler (re-revealable any time via the eye icon). Click Send test to verify your handler signature parsing.
5. Create your first invoice:

   curl -X POST https://payx.lol/api/invoices \
     -H "X-API-Key: <your 64-char hex key>" \
     -H "Content-Type: application/json" \
     -d '{
       "chainId": "tron_mainnet",
       "currency": "USDT",
       "amount": "10.50",
       "redirectUrl": "https://your.shop/order/123/done"
     }'

6. Redirect the buyer to the returned payUrl. Your handler receives a paid event when the chain confirms.

Managed vs monitored mode

Every accepted method is one of two modes. The choice determines what fields you supply at creation time and what shows up on each invoice.

The server only ever sees the public xpub — it can derive but not sign. Most ERC20 / TRC20 token methods are managed-only because the transfer call data has no payer-controllable memo field.

Invoice status lifecycle

new ──> pending ──> partial ──> paid (terminal)
                            ╲
                             ─> expired (terminal, after late window)

new / pending / partial ──> canceled (terminal, merchant-initiated)

• new — created, no payments matched.
• pending — at least one payment detected (any status).
• partial — some confirmed but the total doesn't yet cover the target (after the underpayment tolerance — see below). Stays open through the late window past expiresAt, in case the buyer tops up.
• paid — confirmed amount covers the target.
• expired — late window passed without coverage.
• canceled — you called POST /api/invoices/:id/cancel.
• archived — legacy terminal state for very old rows. New invoices never land here, but the status filter on GET /api/invoices accepts it for historical queries.

Late-payment window

After expiresAt, an invoice that hasn't reached paid enters a grace period (lateWindowMinutes, configurable per account on Settings). Inbound transfers during this window still credit the invoice and flag it is_late: true in the payload. Once the window closes the invoice flips to expired terminal state.

Any inbound transfer that lands on a PayX-tracked address after the invoice is no longer claimable (expired / canceled / gone) surfaces as a separate unmatched event — payment-level, no invoice attached, so your handler can decide whether to refund, credit, or alert.

Cancelling an invoice immediately clips its late-window to now, so a cancelled invoice can never silently re-credit on a delayed payment.

Underpayment tolerance

Crypto rounding, fee rebates and exchange-rate slippage at the buyer's wallet sometimes produce a payment that's a few cents short of the invoiced amount — technically underpaid, practically the order should clear. The underpaymentThresholdRelative setting is the percentage of the invoiced amount the merchant is willing to accept as missing without flipping the invoice to partial.

Default is unset → 0% (strict equality). The merchant must explicitly set a non-zero value on Settings to enable tolerance. Value is a percentage: 0.5 means 0.5%, 1 means 1%.

Concretely, with tolerance set to 0.5: an invoice for 10.00 USDT becomes paid as soon as confirmed transfers sum to ≥ 9.95 USDT. At the default (unset), anything below 10.00 stays partial and the invoice waits through the late window for a top-up.

Address pool & reuse

Managed-mode addresses are reused across invoices when safe. Two reasons PayX doesn't burn a fresh derivation index per invoice:

• TRON charges ~1 USDT to activate every new address. A busy merchant could spend real money on address creation alone.
• Standard wallets (TronLink, Ledger, MetaMask) stop scanning after ~20 consecutive empty addresses on seed import. If the used derivation space has big gaps, funds past a gap become hard to recover without manually extending the scan.

The pool is scoped to your (chain, xpub) — methods that share an xpub share the pool. Each invoice's targetAddress is still dedicated for the invoice's lifetime; what's recycled is the slot after the invoice terminates.

Address states

Which address gets picked for a new invoice

Allocator order: lowest derivation index among eligible addresses. Two eligibility regimes by invoice amount:

• Low-value (amount < highValueThreshold, or threshold unset): any free address.
• High-value (amount ≥ threshold): only addresses that have never received a confirmed payment. Keeps the audit property — each high-value invoice's address has no prior history tied to it.

Pool empty → fall through to deriving a new index on your xpub.

After the invoice ends

Per-method settings

Configurable on both the Add-method form and the inline editor on each managed method card at /methods. The two cooldown fields are pre-filled with your account-level lateWindowMinutes so the merchant always sees the effective value rather than a blank that could read as "hold forever"; change them freely or leave the default.

• highValueThreshold — denominated in the method's currency. Empty = feature off, all invoices share the pool.
• cooldownMinutesPaid — how long a paid address stays out of the pool before being reusable.
• cooldownMinutesUnpaid — same for expired / canceled invoices.

The API keeps null semantics on these cooldown fields (null → fall back to user.lateWindowMinutes) for legacy rows, but any save from the dashboard writes a concrete number.

Late-payment race (important)

If a tardy payer sends to an address after the cooldown has passed and the address has been reused by a new invoice, the payment credits the NEW invoice. PayX can't distinguish intent from the chain. Implications:

• Pick cooldowns longer than the realistic "tardy payer" window in your user base. If your checkout flow typically produces a payment within 30 minutes, a 60-minute unpaid cooldown is generous.
• For high-value invoices you care about auditing cleanly, set highValueThreshold so those invoices get a held address that's never auto-released.
• For monitored-mode methods (single address, memo-attributed) the pool doesn't apply — every invoice shares the one address always.

The Release button on /wallets

For any held address, /wallets shows a Release button. It clears the manual hold AND cancels any open invoice still bound to the address (clipping its late window to now so a tardy payer's transfer surfaces as unmatched rather than accidentally crediting the canceled invoice). Same behaviour as POST /api/wallets/addresses/:id/release.

Authentication

Every endpoint under /api accepts either of:

• Bearer token from the dashboard login flow (Authorization: Bearer <jwt>) — short-lived, refreshed via /api/auth/refresh.
• API key from Settings → API keys (X-API-Key: <key>) — a 64-character hex string generated once per key (no prefix, no visible "live/test" tag — a key is valid for whatever account created it, across any chain). Long-lived, revocable per key, hashed at rest.

Use API keys for server-to-server. The dashboard handles Bearer refresh transparently for browser sessions.

Invoices

Create

Choose the method (required, one of two ways)

Other fields

Optional header Idempotency-Key: <1-255 chars> — sending the same key twice returns the original invoice instead of creating a duplicate.

Supported chain & currency pairs

The full list of chainId values and the currencies enabled on each. Use the dashboard Methods page to actually configure one — listing here is for reference when you don't want to round-trip GET /accepted-methods.

Custom ERC20 / TRC20 tokens beyond the curated list are supported via customContract on accepted-methods create — see Accepted methods.

Response fields

List

Query params: status, cursor, limit, sortBy (createdAt|amount|status|address), sortOrder (asc|desc), includeTestnets=true. Cursor-paginated.

Get one

List the invoice's payments

Cancel

Only open invoices (new / pending / partial) can be cancelled. Cancelled invoices clip their late-payment window to now, so any further inbound transfer will surface as unmatched rather than crediting the cancelled invoice.

Accepted methods

A "method" is a (chain, currency, mode) triple you've configured. Most setup is done from the Methods dashboard page; the API mirrors what the UI does.

Lifecycle

Endpoints

Create body — common fields

Managed-mode-only fields

Monitored-mode-only fields

Custom-token fields (managed mode, EVM chains in practice)

For tokens not in the curated supported pairs table. POST /api/accepted-methods/verify-token helps you populate these by reading symbol and decimals straight from the chain — it only supports EVM adapters, so custom tokens effectively live on EVM only.

Permanent delete (:id/force) refuses if any invoice on the (chain, currency) pair still has its late-window open — so an in-flight payment can never lose the method row needed to credit it.

Wallets

Returns { methods, orphanAddresses }. Each method bundles its derived addresses (managed) or its single address (monitored) with per-address incomingTotal, paymentCount, and the address-pool state flags (cooldownUntil, heldForInvoiceId, manualHold) so the dashboard can label each row. Orphans are addresses whose owning method was hard-deleted; they retain history but won't get new invoices.

Release address to pool

Clears manualHold + cooldownUntil + heldForInvoiceId, and cancels any open invoice still bound to the address in the same transaction. Use case: a partial invoice is sitting in your wallet UI and you've decided not to wait for the top-up, OR a paid high-value invoice was auto-held and you want to put the address back in rotation. Throttled to 60/hour. 404 for foreign addresses (no enumeration leak — same surface as missing).

Settings

URL fields are validated on save: parseable, https-only in production, and any private/loopback hostname is refused.

Rotate the webhook secret

:env is mainnet or testnet. Returns the new secret. Handlers using the old secret start failing signature checks immediately — rotate your handler config in lockstep.

Send a test event

Fires a synthetic test event through the real delivery pipeline so you can verify your handler before any real invoice lands. Throttled to 60/hour. Test events drop on first failure (no retry envelope) — re-clicking is the recovery path.

Webhook configuration

Configure on /settings. Both secrets are auto-generated at registration; reveal them by clicking the eye icon, regenerate any time. Pick how testnet events are routed:

• Dedicated testnet URL + secret — keeps test funds away from your production handler. The testnet secret is auto-generated at signup; you just fill in the URL.
• Same URL as mainnet (toggle testnetUsesMainnetWebhook) — convenient if you run one handler that branches on the payload's is_testnet flag.
• Neither — testnet events are dropped server-side. This is the default state of a new account: a fresh merchant has no testnet URL and the toggle off, so testnet invoices won't emit webhooks until they opt in to one of the first two options. Safe default for production-only integrations.

Event types

Payload shape

{
  "event_id": "8f3c2c1e-…",
  "event_type": "paid",
  "timestamp": "2026-04-20T13:45:12.301Z",
  "is_testnet": false,
  "data": {
    "invoice": {
      "id": "01HXM3…",
      "public_token": "v1_…",
      "status": "paid",
      "amount": "10.50",
      "currency": "USDT",
      "chainId": "tron_mainnet",
      "target_address": "TGcW…",
      "memo": null,
      "is_late": false,
      "is_overpaid": false,
      "client_id": "order-123",
      "metadata": { "your": "stuff" },
      "expires_at": "2026-04-20T14:00:00Z",
      "created_at": "2026-04-20T13:30:00Z"
    },
    "payments": [
      {
        "id": "…",
        "tx_hash": "0xabc…",
        "amount": "10.50",
        "status": "confirmed",
        "from_address": "TPay…",
        "block_number": "67450123"
      }
    ]
  }
}

Notes on a few fields that aren't self-explanatory:

• event_id — unique per delivery. Use it as your idempotency key on the receiving side; a manual retry creates a new event_id for the same logical event.
• is_test — only present on test events. true means "synthetic, ignore in production logic".
• is_late — payment(s) for this invoice arrived during the late-payment window. Order is still valid; you may want to log it for fraud / SLA purposes.
• is_overpaid — confirmed amount exceeds the invoiced amount (buyer sent too much). Decide your refund policy out-of-band.
• memo — only set for monitored-mode invoices. null for managed-mode.
• amount and block_number — strings, not numbers, to preserve precision.

Signature verification

Every delivery includes an X-Signature header containing the HMAC-SHA256 of the raw request body, hex-encoded, signed with your webhook secret for the channel the event came from (mainnet or testnet — see routing).

on POST /your-webhook (request):
    raw_body   = request.body                   # bytes, BEFORE any JSON parse
    signature  = request.headers["X-Signature"] # hex string

    expected = hmac_sha256(secret, raw_body).hex()
    if not constant_time_equal(signature, expected):
        return 401

    payload = parse_json(raw_body)
    handle(payload)
    return 200

import hmac, hashlib, json, os
from flask import Flask, request, abort

app = Flask(__name__)
WEBHOOK_SECRET = os.environ["PAYX_WEBHOOK_SECRET"].encode()

def verify(raw_body: bytes, signature: str) -> bool:
    expected = hmac.new(WEBHOOK_SECRET, raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

@app.post("/payx/webhook")
def webhook():
    raw = request.get_data()  # raw bytes BEFORE Flask parses JSON
    sig = request.headers.get("X-Signature", "")
    if not verify(raw, sig):
        abort(401)

    payload = json.loads(raw)
    if payload.get("is_test"):
        return "", 200  # skip test events in production logic

    event_type = payload["event_type"]
    invoice = payload["data"]["invoice"]

    # Idempotency: dedupe on event_id.
    if event_type == "paid":
        mark_order_paid(client_id=invoice["client_id"], amount=invoice["amount"])
    elif event_type == "expired":
        release_held_inventory(invoice["client_id"])

    return "", 200

// Express + raw-body capture so HMAC sees the unmodified bytes.
import express from "express";
import crypto from "node:crypto";

const app = express();
const WEBHOOK_SECRET = process.env.PAYX_WEBHOOK_SECRET;

// Capture raw bytes BEFORE express.json() reformats the payload.
app.use(
  "/payx/webhook",
  express.raw({ type: "application/json", limit: "100kb" }),
);

app.post("/payx/webhook", (req, res) => {
  const signature = req.header("x-signature") ?? "";
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(req.body) // raw Buffer, not a parsed object
    .digest("hex");

  // constant-time compare — guards against timing attacks
  const ok =
    signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
  if (!ok) return res.status(401).end();

  const payload = JSON.parse(req.body.toString("utf8"));
  if (payload.is_test) return res.status(200).end();

  const { event_type, data } = payload;
  switch (event_type) {
    case "paid":
      markOrderPaid(data.invoice.client_id, data.invoice.amount);
      break;
    case "expired":
      releaseHeldInventory(data.invoice.client_id);
      break;
  }
  res.status(200).end();
});

Mainnet vs testnet routing

The router picks one of three paths at enqueue time, based on the invoice's chain:

• If the chain is mainnet → mainnet URL + mainnet secret.
• If the chain is testnet AND testnetUsesMainnetWebhook = true → mainnet URL + mainnet secret. The payload's is_testnet flag is your branch point.
• If the chain is testnet AND a dedicated testnet URL is set → testnet URL + testnet secret.
• Otherwise (testnet, no fallback) → silently dropped server-side.

Branch on is_testnet in your handler before changing any production state. A sepolia payment must not settle a mainnet order.

Retry behaviour

Real events use a long exponential schedule: 1 m → 5 m → 15 m → 1 h × 24 → 6 h × 28 → failed, with ±10 % jitter at each step. Total envelope ≈ 8 days.

Test events are different. The first non-2xx response drops the delivery to failed immediately, no retry envelope. Test events are diagnostic; re-clicking "Send test" is the recovery path.

A manual retry from the dashboard or API never produces a duplicate delivery if an automatic retry is already queued — once the manual one succeeds, the queued attempt becomes a no-op.

Operational tools

/webhooks shows the full delivery log. Per-row actions:

• Retry — re-sends the event now.
• Cancel — visible on pending rows only. Use when you've handled the payment manually and don't need the webhook to fire.

On any invoice's detail page there's a compact "Webhook" card. If no delivery exists for the invoice yet (you configured webhooks late, or no reportable event has happened), the card offers a Send webhook now button. It maps the invoice's current status to the matching event type (paid → paid, expired → expired, etc.) and fires through the real-event pipeline. Useful when you forgot to set up webhooks before a customer paid.

Endpoints