Fundline Documentation

Architecture

How Fundline works

Fundline separates invoice creation, payment execution and payment verification. The app never holds customer funds. PaymentRouter transfers USDC directly from the payer wallet to the merchant wallet.

Quick start

From invoice to paid status

1. Start the app server.Open run-arc-invoice-server.bat and visit http://127.0.0.1:5190.
2. Connect merchant wallet.The connected wallet becomes the USDC receiving wallet for new invoices.
3. Create an invoice.Add client details, due date, note and line items. Fundline calculates total USDC.
4. Send the payment link.Share the public /pay/:invoiceId link or QR code with the customer.
5. Customer pays.The customer can use the wallet payment button or pay manually and verify the transaction.
6. Receive alerts and receipt.After verification, the invoice becomes paid, Telegram/webhooks run and PDF receipt becomes available.

Wallet setup

Merchant and payer wallets

The merchant must sign in before creating invoices. This signature proves wallet control and fills the receiving wallet automatically. Payers only need to connect when they want to pay directly through the app. If they pay outside the app, they can paste the payer wallet and transaction hash for verification.

Product

Create invoice

An invoice contains client name, client email, due date, note and line items. The server stores invoices in data/invoices.json for local demo usage. Production should move this storage to Supabase, Postgres, or another durable database.

Payment

On-chain payment flow

When PaymentRouter is configured, the public payment page shows a wallet payment button. The payer approves the exact USDC amount, then calls payInvoice(bytes32,address,uint256).

payInvoice(bytes32 invoiceId, address merchant, uint256 amount)

If PaymentRouter is not configured, the payment page keeps the wallet payment button disabled and still supports manual USDC transfer plus Arcscan verification.

Receipts

PDF receipt and CSV export

Paid invoices can generate a professional PDF receipt. The receipt includes invoice number, payer wallet, receiving wallet, transaction hash, verification source and paid timestamp. Merchants can also export CSV for bookkeeping.

Alerts

Telegram payment alerts

Merchants can add a Telegram chat ID in Settings. After a payment is verified, Fundline sends a message with invoice number, amount, payer wallet, receiving wallet and transaction link.

TELEGRAM_BOT_TOKEN=replace_with_telegram_bot_token

Developers and agents

Agent API

Agent API endpoints let a SaaS backend or AI agent create invoices without using the browser dashboard. All Agent API requests require a server-side API key. Use Idempotency-Key when an agent may retry the same create request, so retries return the same invoice instead of creating duplicates.

Authorization: Bearer $FUNDLINE_API_KEY
x-api-key: $FUNDLINE_API_KEY

curl -X POST http://127.0.0.1:5190/api/agent/invoices \
  -H "Authorization: Bearer $FUNDLINE_API_KEY" \
  -H "Idempotency-Key: client-ltd-2026-06-retainer" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantWallet": "0x8124ca3f0ca935e6beb69f2857e33d32fa3b54ea",
    "merchantName": "Fundline Studio",
    "clientName": "Client Ltd",
    "clientEmail": "billing@client.com",
    "dueDate": "2026-06-30",
    "items": [
      { "description": "Consulting package", "quantity": 1, "unitPrice": 250 }
    ]
  }'

Webhooks

Payment events for external systems

Webhooks notify your backend when an invoice becomes paid. A webhook can be signed with X-Fundline-Signature using HMAC SHA-256.

curl -X POST http://127.0.0.1:5190/api/agent/webhooks \
  -H "Authorization: Bearer $FUNDLINE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantWallet": "0x8124ca3f0ca935e6beb69f2857e33d32fa3b54ea",
    "url": "https://example.com/webhooks/fundline",
    "event": "invoice.paid",
    "secret": "optional_shared_secret"
  }'

{
  "event": "invoice.paid",
  "sentAt": "2026-06-11T00:00:00.000Z",
  "invoice": {
    "id": "37f1cdd4727c0d85d32b",
    "number": "INV-2026-0001",
    "status": "paid",
    "total": 250,
    "merchantWallet": "0x...",
    "payerWallet": "0x...",
    "txHash": "0x...",
    "paymentLink": "http://127.0.0.1:5190/pay/37f1cdd4727c0d85d32b"
  }
}

Delivery audit

Webhook logs

Each webhook delivery attempt is stored on the server with delivery ID, invoice ID, target URL, success state, HTTP status, error preview and duration. Secrets are never returned in log responses.

curl "http://127.0.0.1:5190/api/agent/webhook-logs?merchantWallet=0x8124ca3f0ca935e6beb69f2857e33d32fa3b54ea&limit=20" \
  -H "Authorization: Bearer $FUNDLINE_API_KEY"

Reference

Network

Contracts

PaymentRouter

PaymentRouter was deployed to Arc Testnet to enable direct USDC invoice payments from payer wallet to merchant wallet.

Configuration

Server environment

All secrets stay on the server. Do not expose private keys, Telegram bot token or API key in browser code.

TELEGRAM_BOT_TOKEN=replace_with_telegram_bot_token
FUNDLINE_API_KEY=replace_with_a_long_random_agent_api_key
ARC_DEPLOYER_PRIVATE_KEY=replace_with_testnet_deployer_private_key
ARCSCAN_API_BASE=https://testnet.arcscan.app/api/v2
ARCSCAN_EXPLORER_BASE=https://testnet.arcscan.app
ARC_CHAIN_ID=5042002
ARC_RPC_URL=https://rpc.testnet.arc.network
ARC_NETWORK_NAME=Arc Testnet
ARC_USDC_TOKEN_ADDRESS=0x3600000000000000000000000000000000000000
ARC_NATIVE_USDC_DECIMALS=18
ARC_PAYMENT_ROUTER_ADDRESS=0x7f3bCf33711F981e2d67870D5Cdb5503f01e1a24

Security

Security baseline

• PaymentRouter is non-custodial and does not hold USDC.
• The payer approves only the invoice amount required by the payment page.
• Paid status is set only after Arcscan returns a matching payment.
• Telegram bot token, API key and deployer private key stay in server-side environment files.
• Webhook signatures should be verified by production receivers before trusting payloads.

FAQ

Common questions