> ## 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.

# Quickstart

> Create your first stablecoin payment in 5 minutes

# Quickstart

This guide walks you through creating a payment intent, rendering a QR code, and receiving a webhook when the customer pays. The entire integration is two API calls.

<Info>
  The Stable Genius API is currently in private beta. [Request early access](https://stablegenius.co/early-access) to get your API keys.
</Info>

## Prerequisites

* A Stable Genius account with API keys (`sk_test_...` for sandbox, `sk_live_...` for production)
* A merchant onboarded through the [Stable Genius dashboard](https://app.stablegenius.co) with KYC completed and bank account linked
* Your webhook endpoint URL registered in the dashboard

## Step 1: Create a Payment Intent

When a customer is ready to pay, create a payment intent. This returns a payment address and QR code payload that the customer scans with their wallet.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.stablegenius.co/v1/payment-intents \
    -H "Authorization: Bearer sk_test_abc123" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 4.50,
      "currency": "usd",
      "merchant_id": "mer_abc123",
      "metadata": {
        "order_id": "order_456",
        "terminal_id": "pos_01"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.stablegenius.co/v1/payment-intents', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_abc123',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: 4.50,
      currency: 'usd',
      merchant_id: 'mer_abc123',
      metadata: {
        order_id: 'order_456',
        terminal_id: 'pos_01',
      },
    }),
  });

  const paymentIntent = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.stablegenius.co/v1/payment-intents',
      headers={
          'Authorization': 'Bearer sk_test_abc123',
          'Content-Type': 'application/json',
      },
      json={
          'amount': 4.50,
          'currency': 'usd',
          'merchant_id': 'mer_abc123',
          'metadata': {
              'order_id': 'order_456',
              'terminal_id': 'pos_01',
          },
      },
  )

  payment_intent = response.json()
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "pi_xyz789",
  "object": "payment_intent",
  "status": "awaiting_payment",
  "amount": 4.50,
  "currency": "usd",
  "merchant_id": "mer_abc123",
  "payment_address": "0x1a2b3c4d5e6f...abcdef",
  "chain": "base",
  "token": "USDC",
  "qr_payload": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x1a2b3c4d5e6f...abcdef&uint256=4500000",
  "qr_image_url": "https://api.stablegenius.co/v1/qr/pi_xyz789.png",
  "expires_at": "2026-04-01T20:05:00Z",
  "metadata": {
    "order_id": "order_456",
    "terminal_id": "pos_01"
  },
  "created_at": "2026-04-01T20:00:00Z"
}
```

## Step 2: Display the QR Code

Render the QR code on your terminal, app, or checkout page. You have two options:

**Option A: Render the QR payload yourself** — Use `qr_payload` with any QR code library. This is the [EIP-681](https://eips.ethereum.org/EIPS/eip-681) standard that wallets like Coinbase Wallet and MetaMask understand natively.

**Option B: Use our hosted QR image** — Display `qr_image_url` directly as an image. No QR library needed.

```javascript theme={null}
// Option A: Render with a QR library (e.g., qrcode.js)
import QRCode from 'qrcode';

const qrDataUrl = await QRCode.toDataURL(paymentIntent.qr_payload);
document.getElementById('qr').src = qrDataUrl;

// Option B: Use hosted image
document.getElementById('qr').src = paymentIntent.qr_image_url;
```

The customer scans the QR code with their wallet (Coinbase Wallet, MetaMask, Phantom, etc.), sees the pre-filled transfer, and taps confirm.

## Step 3: Receive the Webhook

When the payment confirms on-chain, we send a `payment_intent.confirmed` event to your registered webhook URL:

```json theme={null}
{
  "id": "evt_abc123",
  "object": "event",
  "type": "payment_intent.confirmed",
  "created_at": "2026-04-01T20:00:12Z",
  "data": {
    "id": "pi_xyz789",
    "object": "payment_intent",
    "status": "confirmed",
    "amount": 4.50,
    "currency": "usd",
    "net_amount": 4.455,
    "fee": 0.045,
    "merchant_id": "mer_abc123",
    "tx_hash": "0xabc123...def456",
    "chain": "base",
    "token": "USDC",
    "confirmed_at": "2026-04-01T20:00:12Z",
    "metadata": {
      "order_id": "order_456",
      "terminal_id": "pos_01"
    }
  }
}
```

Your system processes the webhook and marks the order as paid:

```javascript theme={null}
app.post('/webhooks/stablegenius', (req, res) => {
  const event = req.body;

  // Verify webhook signature (see Webhook Security)
  // verifySignature(req);

  if (event.type === 'payment_intent.confirmed') {
    const { amount, tx_hash, metadata } = event.data;

    // Mark order as paid in your system
    markOrderPaid(metadata.order_id, {
      amount,
      tx_hash,
      paid_at: event.data.confirmed_at,
    });

    // Trigger your POS to show success (beep, receipt, etc.)
    notifyTerminal(metadata.terminal_id, 'payment_success');
  }

  res.status(200).json({ received: true });
});
```

**That's it.** The merchant's funds settle automatically to their bank account on the configured withdrawal schedule. You don't manage wallets, watch blockchains, or handle settlements.

## Next Steps

<CardGroup cols={2}>
  <Card title="Payment Intents" icon="file-invoice-dollar" href="/concepts/payment-intents">
    Understand the full payment intent lifecycle
  </Card>

  <Card title="Webhooks" icon="bell" href="/concepts/webhooks">
    Learn about all webhook events and verification
  </Card>

  <Card title="Testing" icon="vial" href="/guides/testing">
    Set up your sandbox environment
  </Card>

  <Card title="POS Integration" icon="cash-register" href="/guides/pos-terminal">
    Build a terminal integration step-by-step
  </Card>
</CardGroup>