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

# How It Works

> End-to-end payment flow from customer scan to merchant bank deposit

# How It Works

Stable Genius handles the entire payment lifecycle: from the moment a customer scans a QR code to when dollars land in the merchant's bank account. Your integration touches two points — creating the payment and receiving the confirmation.

## Payment Flow

```mermaid theme={null}
sequenceDiagram
    participant Integrator as Your System
    participant SG as Stable Genius API
    participant Customer as Customer Wallet
    participant Chain as Blockchain (Base)
    participant Bank as Merchant's Bank

    Integrator->>SG: POST /v1/payment-intents
    SG-->>Integrator: Payment address + QR payload
    Integrator->>Customer: Display QR code
    Customer->>Chain: Send USDC to payment address
    Chain->>SG: Transaction detected (webhook)
    SG->>SG: Validate, split fees, settle
    SG->>Integrator: Webhook: payment_intent.confirmed
    Integrator->>Integrator: Mark order as paid
    SG->>Bank: ACH settlement (automatic)
```

## Step by Step

### 1. Create a Payment Intent

Your system calls `POST /v1/payment-intents` with the amount and merchant ID. We return a payment address (the merchant's on-chain proxy contract) and a QR code payload formatted as an [EIP-681](https://eips.ethereum.org/EIPS/eip-681) URI.

### 2. Customer Scans and Pays

The customer scans the QR code with any compatible wallet (Coinbase Wallet, MetaMask, Phantom, etc.). The wallet displays a pre-filled USDC transfer. The customer taps confirm. The transaction is submitted to the blockchain.

### 3. On-Chain Confirmation

Our infrastructure monitors the blockchain for incoming USDC transfers to merchant payment addresses. When a transfer is confirmed, we process it automatically:

* **Transaction recorded** in the merchant's ledger
* **Fee split** executed on-chain (configurable, default 1%)
* **Net amount** settled to the merchant's smart contract wallet

### 4. Webhook Delivered

We fire a `payment_intent.confirmed` webhook to your registered URL with the full transaction details: amount, fee, net amount, transaction hash, and any metadata you attached to the payment intent.

### 5. Settlement to Bank

Merchant funds are automatically withdrawn from their on-chain wallet and converted to USD via ACH bank transfer. Settlement options:

* **Automatic weekly** — Every Monday at 8am EST
* **Manual cash-out** — Merchant triggers from the dashboard anytime
* **Custom schedule** — Configurable per merchant

## Key Design Principles

<CardGroup cols={2}>
  <Card title="Non-Custodial" icon="shield-halved">
    Merchant funds settle to smart contracts they control. Stable Genius never holds merchant funds. Merchants can emergency withdraw directly from their contract at any time.
  </Card>

  <Card title="On-Chain Verifiable" icon="link">
    Every transaction, fee split, and settlement is recorded on-chain. Merchants and integrators can verify any transaction on Basescan independently.
  </Card>

  <Card title="Chain Agnostic (Roadmap)" icon="shuffle">
    Settlement is on Base today. Multi-chain support (Solana, Arbitrum, Optimism) is on our roadmap. Your integration won't change when new chains go live.
  </Card>

  <Card title="Fiat Settlement" icon="building-columns">
    Merchants don't manage crypto. USDC is automatically converted to USD and deposited in their bank account via ACH. 1-3 business day settlement.
  </Card>
</CardGroup>