> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fundwork.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Fundwork Payment Architecture

> How Fundwork denominates payments in USDC on Base, how direct settlement works today, and how escrow will fit into the production architecture.

Fundwork denominates marketplace payments in USDC on Base. This page describes how payments are structured today, how the backend verifies settlement, and how escrow will fit into the architecture over time.

<Note>
  Fundwork is in **alpha**. Direct settlement is the current model. Smart-contract escrow is part of the planned production architecture and is described further on [Escrow Design](/technical/escrow-design).
</Note>

## Two Payment Models

Fundwork's payment architecture has two distinct modes that address different needs.

### Direct settlement (current)

For the earliest version of the marketplace, direct client-to-worker payments may be used for approved work while Fundwork verifies and records settlement. This keeps the smart-contract surface small during alpha while core marketplace behavior is validated.

### Smart-contract escrow (planned)

Longer term, Fundwork intends to support smart-contract-based escrow for workflows where funds need to be committed before work begins. Escrow is described in detail on [Escrow Design](/technical/escrow-design).

The two models coexist. Some opportunity types will benefit from committing funds up front; others will settle directly on approval.

## Direct Settlement Flow

The direct settlement flow is:

<Steps>
  <Step title="Client approves the work">
    The client approves the submission or milestone inside Fundwork. The backend records the approval intent and prepares the payment.
  </Step>

  <Step title="Client authorizes the payment">
    The client authorizes a USDC transfer to the worker's payout address. In the target UX this authorization goes through Base Account with gas potentially sponsored by Fundwork.
  </Step>

  <Step title="USDC moves on Base">
    The USDC transfer is submitted to Base and included in a block. A transaction hash is returned.
  </Step>

  <Step title="Backend verifies the transfer">
    The Fundwork backend independently verifies the transfer against Base before treating it as settled.
  </Step>

  <Step title="State updates">
    Once verification succeeds, the payment record is marked confirmed and the opportunity or milestone state advances to **Paid**.
  </Step>
</Steps>

## Server-Side Verification

A core rule in the Fundwork architecture:

<Warning>
  Fundwork must never trust frontend success alone. A UI reporting a successful transaction is not evidence that a payment occurred.
</Warning>

Before a payment record is marked confirmed, the backend verifies all of the following against Base:

* **Transaction exists** on the expected network.
* **Transaction succeeded** (not reverted).
* **Correct network** (Base, matching the expected chain ID).
* **Correct asset** (the canonical USDC contract on Base).
* **Correct amount** matches the expected value for the opportunity or milestone.
* **Correct sender** where the sender is known and expected.
* **Correct recipient** matches the worker's configured payout address.
* **Transaction has not already been consumed** by another payment record.

Each of these checks is independent. A transaction that fails any check is not treated as a successful payment, regardless of what the frontend reports.

### Replay protection

Every confirmed transaction hash is recorded and cannot be reused to settle a different payment record. This prevents an attacker from re-submitting a valid onchain transaction to trigger duplicate state changes.

### Idempotency

Backend payment verification is idempotent: verifying the same transaction hash multiple times produces the same result and does not create duplicate records or state transitions.

## Why USDC on Base

The choice of USDC on Base is not incidental. It follows from a few properties Fundwork needs:

* **Stable unit of account.** USDC is USD-pegged, so the amount a client approves is the amount the worker receives.
* **Onchain verifiability.** Every transfer has a public transaction hash, which is exactly what the backend needs to verify settlement.
* **Low fees and fast finality.** Base's L2 economics make it practical to settle small payments quickly.
* **Smart-wallet-friendly.** Base Account fits naturally with the account abstraction direction described in [Accounts & Authentication](/technical/accounts-and-authentication).

See [Why USDC](/payments/why-usdc) and [Why Base](/payments/why-base) for consumer-facing background.

## What Payments Do Not Do

A few explicit non-claims about the current payment architecture:

* Fundwork does not custody user funds in a shared platform wallet during direct settlement.
* Fundwork does not treat frontend-reported success as authoritative.
* Fundwork does not currently move funds through a deployed escrow contract. Escrow is planned; see [Escrow Design](/technical/escrow-design).
* Fundwork does not guarantee that a worker will receive payment for work that has not been approved.

## Where to Read Next

<CardGroup cols={2}>
  <Card title="Escrow Design" icon="vault" href="/technical/escrow-design">
    The planned escrow lifecycle, states, and design principles.
  </Card>

  <Card title="Security" icon="shield-halved" href="/technical/security">
    How server-side verification fits into the broader security model.
  </Card>

  <Card title="Dispute Resolution" icon="scale-balanced" href="/technical/dispute-resolution">
    How disputes will interact with settlement.
  </Card>

  <Card title="Gasless Transactions" icon="gas-pump" href="/technical/gasless-transactions">
    Paymaster policy for sponsoring eligible Base transactions.
  </Card>
</CardGroup>