Merchant payments: links, invoices and hosted checkout

A merchant creates a payment link, an invoice or a terminal request for an exact USDC amount. The payer opens a hosted checkout, chooses a network and sends native USDC from their own wallet to a destination reserved for that one checkout. FurlPay marks the payment paid only after it has read the transfer back from the chain.

What a merchant can create

Amounts are decimal strings with up to six decimals, above zero and at most 1,000,000 USDC. They are stored as integer micro-units; no floating-point arithmetic touches a payment amount.

Networks and confirmation depth

Only Circle-issued native USDC is accepted. A network is collectable only when it has a reviewed deposit policy; the required depth is the stricter of that policy and the payment registry. The checkout offers the networks that currently have an unassigned destination for the merchant.

Fees

Each link records the merchant's processing rate when it is created. Rates are tiers assigned by operations: starter 95, growth 75, scale 50 and enterprise 35 basis points. A merchant with no assigned tier pays the growth rate. The fee is rounded down to the smallest USDC unit. The merchant chooses who pays it:

• Merchant pays — the payer is charged the gross amount; the merchant nets gross minus fee.
• Customer pays — the payer is charged gross plus fee; the merchant nets the gross amount.

Network gas is separate and is always paid by the payer's wallet.

Checkout flow

• The merchant creates a link. The response contains a 24-character opaque slug; the hosted page is /p/<slug>. Payers are anonymous and need no account.
• The payer picks a network. FurlPay reserves one never-reused destination address for this checkout and records the chain height at that moment.
• The checkout shows a payment request and QR code for the payer's wallet.
• While the page is open it polls the checkout endpoint, which runs the verifier. A scheduled job runs the same verifier every two minutes, so confirmation does not depend on the page staying open.
• When the required depth is reached and screening passes, the receipt, ledger posting, status change and webhook event are committed together.

Payment statuses

How a payment is verified

The client never reports a payment. The verifier reads the transfer to the reserved address from the network, checks it independently against the transaction receipt, confirms the network identity and that the node head is fresh, and re-checks that the block is still canonical. Before crediting, the payer and the destination are screened (see Screening and cases).

If a node is unreachable the checkout keeps its last proven state and reports that verification is delayed. An outage is never turned into a success or a failure. A transfer is recorded once per network, transaction and log position, so a duplicate scan cannot credit twice.

Receipts

A one-page PDF receipt is issued only for a payment the verifier credited (paid or overpaid). An underpaid, confirming or held payment has no receipt.

Refunds

On-chain payments cannot be reversed, so a refund is a new transfer back to the payer. Requesting one reserves the amount in the ledger immediately. Operations approve it, and the custody provider that controls the collection addresses sends it. The refund is marked complete only when that transfer is read on-chain.

Reconciliation and alerts

Every ten minutes a scheduled job compares three records: the intent, the ledger and the chain. Recently recorded receipts are re-read from the network and must still be a successful, canonical USDC transfer of the recorded amount to the intent's address. It also raises liveness alerts for payments stuck confirming, a scanner that has stopped, held payments nobody has reviewed, and a network whose head is stale. Findings become alerts for operations. The job never edits an intent, reverses a journal or changes a merchant balance.

API

curl -X POST https://furlpay.com/api/merchant/payments \
  -H "content-type: application/json" \
  -b "session" \
  -d '{
    "requestId": "7d0a5c4e-2c1b-4b7e-9a51-3f2d6c8e1a90",
    "kind": "link",
    "title": "Annual plan",
    "description": "",
    "amount": "250.00",
    "chains": ["base", "arbitrum"],
    "reusable": false,
    "feePayer": "merchant",
    "expiresAt": null,
    "reference": "ORDER-1042",
    "lines": []
  }'

Merchant routes use the signed-in session; the merchant is always the authenticated account and no merchant ID is accepted from the client. The public checkout routes are rate limited per IP.

Responses to handle

• 409 on reserve — the link is closed, or a single-use checkout is already in progress.
• 503 on reserve — the network is not ready (no destination, or the node could not be verified). No payment was requested.
• 503 on merchant routes — payment storage is not configured or a migration is not applied.

Webhook events

A verified payment writes payment.succeeded to the merchant's outbox, and invoice.paid when the link is an invoice. Delivery, signature format and retry schedule are described in Webhook Events. The webhook is a notification; the payment record returned by the API is the source of truth.

Where merchants manage this

• /dashboard/payments, /dashboard/payment-links, /dashboard/invoices and /dashboard/qr — the merchant workspace (sign-in required).
• /dashboard/operations — the operator console.
• /p/<slug> — the public hosted checkout for one link.

Setup

• Database — Supabase configured, with migrations 0040 (payments), 0041 (webhooks), 0042 (pricing tiers, reconciliation), 0043 (Sui), 0045 (refunds), 0046 (liveness alerts) and 0047 (Arc testnet) applied in order.
• Collection addresses — registered through the operator console. Registration requires proof of control: the address itself signs a message naming the merchant, network, address and custody reference. FurlPay never generates, derives or stores keys for collection addresses. Each address is used for exactly one checkout, and there is no fallback to a shared address.
• Node endpoints — BASE_RPC_URL, ARBITRUM_RPC_URL, ETHEREUM_RPC_URL, POLYGON_RPC_URL, SOLANA_RPC_URL, ARC_RPC_URL and SUI_GRAPHQL_URL, with optional _SECONDARY endpoints for failover. Unset values fall back to public endpoints, which are rate limited.
• Scheduled jobs — /api/cron/merchant-payments every two minutes and /api/cron/merchant-reconcile every ten, both listed in vercel.json. Sub-daily schedules depend on the hosting plan.
• Webhook secrets — FURLPAY_PARTNER_WEBHOOK_KEY seals merchant signing secrets at rest.
• Check — npm run merchant:check-env reports what is missing. npm run merchant:seed-destinations registers pilot addresses on a local or staging database only; it refuses the production project.