How to Detect On-Chain Invoice Payments Automatically

Before automatic detection, merchants refreshed block explorers manually — "Did the client pay yet?" — and AP teams Slack-pinged across time zones. Detection automation is the difference between crypto invoicing as a hobby and crypto invoicing as infrastructure.

This guide explains what detection must verify, how architectures work per network, failure modes, and build-vs-buy decisions.

What "paid" means on-chain

An invoice is not paid when:

• Client emails "sent"
• Transaction appears in mempool (unconfirmed)
• Wrong token arrives at address
• Underpayment arrives without partial handling policy
• Payment arrives at wrong network address format

An invoice is paid when:

• Transfer targets this invoice's deposit address
• Token matches expected mint/contract (USDC not fake "USDC")
• Amount ≥ expected minus tolerance
• Transaction achieves required confirmations (confirmation guide)
• Event recorded with tx hash/signature linked to invoice ID

Detection systems implement all five programmatically.

Detection pipeline architecture

Dual-source verification cross-checks indexer against RPC — reduces false positives from indexer bugs or chain reorganizations.

Per-network detection differences

Unified invoice API hides this complexity — merchant sees invoice.paid.

Solana specifics: accept Solana USDC invoices.

EVM specifics: filter Transfer event logs on USDC contract where to == deposit_address.

Address registry at invoice creation

When invoice issues:

Registry must update before client can pay — race where client pays before registration causes missed detection (recoverable via reconciliation scan, but SLA hit).

Non-custodial binding proves deposit address maps to merchant settlement wallet at creation — address-bound settlement.

Mint and contract verification (critical)

USDC has official deployments per chain:

Detection must whitelist mints — accepting any SPL/ERC-20 token enables fake token attacks where worthless tokens mark invoice paid if logic only checks amount number.

Amount matching and tolerance

Configure tolerance for exchange withdrawal rounding. Enterprise treasuries may require exact — document in invoice terms.

Overpayment: mark paid; flag overage for manual credit or refund.

Confirmation thresholds and finality

Speed vs safety tradeoff:

On-chain payment confirmation details reorg risk by chain.

Detection should downgrade status if reorg removes tx (rare) — invoice returns to open.

Mempool monitoring: usually skip

Some systems credit on mempool for UX — risky:

• Transaction dropped from mempool → false paid state
• Replace-by-fee attacks on Bitcoin (less relevant USDC EVM)

Best practice: pending UI state separate from paid; only webhook on confirmation.

Partial payments and multi-tx settlement

Client sends 3000 + 2000 USDC in two txs:

Detection aggregates per invoice address within payment window:

Or requires single tx — platform policy. Aggregation improves UX for exchange limits.

Expired invoices and late payments

Invoice expires after due date + grace:

Non-custodial systems generate new address per invoice — late payment to expired address needs manual reconciliation support ticket.

Webhook emission after detection

Detection engine emits internal event → webhook dispatcher:

Reliable delivery: retries, signing, idempotency — webhook integration guide.

Latency target: sub-minute after confirmation for SaaS fulfillment SLAs.

DIY build estimate

Engineering cost to build production-grade multi-chain detection:

Most product companies buy via Settlematic Collect unless blockchain infra is core competency.

Failure modes and mitigations

Reconciliation with accounting

Detection timestamp drives cash-basis revenue recognition. Export includes:

• detected_at vs block_timestamp — should align closely
• confirmations_at_detection

Accountants reconcile exports to chain — accountant guide.

Testing detection logic

Before mainnet:

• Demo sandbox — testnet payments
• Simulate partial payment
• Simulate wrong mint (should reject)
• Replay webhook twice (idempotency)
• Load test 100 open invoices — no missed registrations

Test crypto payments sandbox.

Security of detection layer

Detection compromise could mark unpaid invoices paid without on-chain payment — catastrophic if webhooks unlock goods.

Controls:

• Detection service internal-only; no merchant override "mark paid" without tx hash audit
• Admin manual mark requires hash verification on chain
• Hash linked in immutable audit log
• Separate read-only explorer link in dashboard for human verification

Is crypto invoicing safe covers shared responsibility.

Operational monitoring

Dashboards for platform operators (merchants care about outcomes):

• Open invoices aging
• Detection lag p95
• Webhook failure rate
• Unmatched on-chain transfers to known addresses (support queue)

Merchants enable email/Slack on paid — reduce need to watch dashboard.

Relationship to non-custodial settlement

Detection observes — never controls funds. Unlike custodial processors where "payment detected" triggers internal ledger credit then payout queue, non-custodial detection updates invoice status while funds already sit in merchant-controlled derivation path.

Clarifies custodial vs non-custodial webhook semantics.

When manual detection still happens

• Client pays wrong network to wrong address — support manual match if recoverable
• Legacy invoice before automation adoption — one-time import
• Charitable rounding disputes — human judgment

Target: <1% manual intervention rate at steady state.

Historical backfill and migration

Merchants migrating from manual wallet to Settlematic Collect mid-year:

• Export manual payment log (spreadsheet) for Jan–migration date
• Platform export covers migration date–Dec 31
• Concatenate with consistent columns for tax prep
• Never double-count payments appearing in both sources

Optional: enter historical paid invoices as paid status with manual tx hash for unified dashboard — platform support may assist bulk import.

Detection SLA commitments for customer-facing products

If your SaaS promises instant access on payment, internal SLA stack:

Total user-visible: often under 1 minute on Solana/Base — competitive with card auth for digital goods.

Comparison: detection vendors vs full invoicing platform

Buy invoicing platform when invoice metadata drives business logic — build raw detection only if invoices are not your model.

Monitoring alerts for merchants

Configure notifications:

• Invoice >$10k paid — CFO email
• Detection lag >5 min — engineering Slack
• Partial payment received — AR team
• Invoice expired unpaid — account manager follow-up

Proactive alerts beat client asking "did you get my payment?"

Indexer vs RPC: when each wins

Settlematic absorbs this complexity — merchants should not run personal indexers for invoice AR unless building custom products.

Stuck invoice playbook for support teams

• Client claims paid — request tx hash/signature
• Lookup hash on correct explorer
• Compare destination to invoice deposit address
• If match + confirmed + wrong status → detection bug ticket
• If wrong address → client sent to stale invoice — education
• If wrong mint → reject; client must send USDC

Median resolution time under 15 minutes with trained support and explorer fluency.

Latency budgets across the detection stack

Merchants selling digital goods with instant-access SLAs should document end-to-end latency budgets. Example for $500 USDC invoice on Base:

Total merchant-visible: often 15–60 seconds on L2/Solana. Ethereum L1 adds 3–15 minutes for conservative confirmation policies — set customer expectations accordingly on invoice terms.

Measure paid_at minus block_timestamp monthly; p95 lag exceeding 60 seconds on Solana warrants support ticket to platform — not normal operations.

Handling chain upgrades and hard forks

Detection systems must survive network upgrades without false negatives:

• Solana — Monitor cluster upgrade announcements; RPC providers update before mainnet; verify detection resumes within 1 hour post-upgrade in staging.
• Ethereum L2s — Sequencer upgrades rarely affect ERC-20 Transfer log format; test receipt parsing after major OP Stack releases.
• Hard forks — Dual-source verification prevents marking paid on orphaned chain tip during contentious forks (extremely rare for invoice use cases but architecturally handled).

Merchant action during announced maintenance: none required for non-custodial detection — payments accumulate on-chain; backlog clears when indexers catch up. Communicate to clients only if platform publishes maintenance window exceeding 4 hours.

Detection accuracy metrics to track

Export metrics from platform dashboard if available; otherwise sample 50 payments monthly with independent explorer verification. CFO-facing report: "99.7% of payments auto-detected within 1 minute" builds confidence in crypto AR automation.

Integration with dunning and collections workflows

Detection enables automated collections — not just fulfillment:

Subscribe to invoice.created, invoice.partially_paid, and invoice.expired webhooks alongside invoice.paid. Collections automation reduces DSO without manual dashboard monitoring.

Partial payment detection prevents premature collections — if client sent 80% on day 6, reminder on day 8 should acknowledge partial and request remainder only.

Build vs buy decision matrix (expanded)

Build only if blockchain infrastructure is your core product. Everyone else buys detection and ships invoicing features — pricing comparison against engineer salary makes the math obvious for teams under 500 invoices/month.

Reconciliation lag monitoring and merchant-side alerting

Detection lag — time between on-chain confirmation and invoice status update — should be monitored as a first-class operational metric, not discovered when support tickets spike. Merchants can approximate lag by comparing block timestamp from explorer against paid_at in platform export monthly; p95 exceeding sixty seconds on Solana or Base warrants platform support inquiry. Configure merchant-side alerts: if invoice remains open more than ten minutes after client provides tx hash that explorer shows confirmed to correct address, escalate to support with hash and invoice ID.

Build internal dashboard widget tracking open invoices with client-reported payment older than thirty minutes — bridges gap between platform detection and client communication. During indexer outages, lag may spike to hours while funds remain safe on-chain; communicate proactively to clients with pending payments rather than waiting for complaints. Post-outage, run reconciliation scan for payments during outage window before resuming fulfillment automation — backlog processing may deliver webhooks in burst; ensure idempotent handlers tolerate burst without duplicate side effects.

Historical backfill scans and missed payment recovery

Detection systems occasionally miss payments during brief registry race conditions, indexer gaps, or client paying before address registration completes. Platform reconciliation jobs scan historical chain activity against open invoice addresses — merchant action usually none required if platform handles backfill. DIY builders must implement periodic backfill: nightly job queries indexer for transfers to all open invoice addresses in last seventy-two hours, compares against paid status, flags discrepancies.

Missed detection recovery differs from wrong-chain recovery — funds arrived at correct address on correct network but status not updated. Support resolution: manual mark paid with tx hash after verification, then investigate detection gap. Prevent recurrence by ensuring invoice payment page does not display deposit address until registry confirms registration complete. Document backfill scan frequency in runbook; auditors asking "could payment arrive without being recorded?" need answer demonstrating automated reconciliation within twenty-four hours.

Merchants running high-volume seasonal campaigns should temporarily increase backfill scan frequency to hourly during peak weeks — Black Friday payment bursts expose edge cases that monthly reconciliation misses until January close panic.

Log every manual mark-paid intervention with operator ID and reason code — patterns in manual interventions reveal detection gaps worth engineering tickets to platform support.

Publish monthly detection health report to stakeholders: auto-detected percentage, average lag, manual intervention count, top failure reason. Transparency builds finance confidence in crypto AR automation.

Set alert threshold: manual intervention rate above two percent for two consecutive weeks triggers UX review of payment page network labeling and client onboarding materials.

Automatic on-chain invoice payment detection turns blockchain settlement into closed-loop AR — verify mint, amount, address, and confirmations, then mark paid and fire webhooks. Building multi-chain detection is expensive; Settlematic Collect ships dual-source verification with non-custodial settlement. Test flows in demo, integrate webhooks, and compare pricing against engineering cost to build in-house.