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

# Create Payment Intent

> Create a new payment intent for a merchant

# Create Payment Intent

Creates a payment intent and returns the payment address and QR code for the customer to scan.

## Request

<ParamField body="amount" type="number" required>
  Payment amount in USD. Minimum: 0.01. Maximum: 10000.
</ParamField>

<ParamField body="currency" type="string" required>
  Currency code. Currently only `"usd"` is supported.
</ParamField>

<ParamField body="merchant_id" type="string" required>
  The merchant's Stable Genius ID (format: `mer_*`).
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs to attach to the payment intent. Max 10 keys, 500 characters per value. Returned in webhooks.
</ParamField>

<ParamField body="ttl" type="integer">
  Time-to-live in seconds. Default: 300 (5 minutes). Min: 60. Max: 3600.
</ParamField>

<ParamField body="idempotency_key" type="string">
  Unique key for idempotent requests. If the same key is sent within 24 hours, the existing payment intent is returned.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Unique payment intent ID (format: `pi_*`).
</ResponseField>

<ResponseField name="object" type="string">
  Always `"payment_intent"`.
</ResponseField>

<ResponseField name="status" type="string">
  `"awaiting_payment"` on creation.
</ResponseField>

<ResponseField name="amount" type="number">
  Payment amount in USD.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code (`"usd"`).
</ResponseField>

<ResponseField name="merchant_id" type="string">
  The merchant receiving the payment.
</ResponseField>

<ResponseField name="payment_address" type="string">
  On-chain address for the customer to send USDC to.
</ResponseField>

<ResponseField name="chain" type="string">
  Blockchain network (e.g., `"base"`).
</ResponseField>

<ResponseField name="token" type="string">
  Token symbol (e.g., `"USDC"`).
</ResponseField>

<ResponseField name="qr_payload" type="string">
  EIP-681 formatted URI for QR code rendering. Compatible with Coinbase Wallet, MetaMask, and other EIP-681 wallets.
</ResponseField>

<ResponseField name="qr_image_url" type="string">
  URL to a hosted PNG image of the QR code (400x400px).
</ResponseField>

<ResponseField name="expires_at" type="string">
  ISO 8601 timestamp when the payment intent expires.
</ResponseField>

<ResponseField name="metadata" type="object">
  Your attached metadata.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

<RequestExample>
  ```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()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "pi_xyz789",
    "object": "payment_intent",
    "status": "awaiting_payment",
    "amount": 4.50,
    "currency": "usd",
    "merchant_id": "mer_abc123",
    "payment_address": "0x1a2b3c4d5e6f7890abcdef1234567890abcdef12",
    "chain": "base",
    "token": "USDC",
    "qr_payload": "ethereum:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913@8453/transfer?address=0x1a2b3c4d5e6f7890abcdef1234567890abcdef12&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"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": {
      "type": "invalid_request_error",
      "message": "Amount must be between 0.01 and 10000",
      "param": "amount",
      "code": "amount_out_of_range"
    }
  }
  ```
</ResponseExample>