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

# Create Payment

> Create an invoice and generate a deposit address in a single call

Creates an invoice and generates a deposit address in one request. The customer can start paying immediately — no second call needed.

Use this instead of [Create Invoice](/api-reference/invoices/create) when you already know which chain and token the customer will pay with (e.g. your checkout UI lets them choose before you call the API).

## Request

<ParamField body="amount" type="string" required>
  Invoice amount as a decimal string. Must be greater than 0.

  **Example:** `"49.99"`
</ParamField>

<ParamField body="currency" type="string" required>
  Fiat currency of the invoice. Supported: `USD`, `EUR`, `GBP`, etc.

  **Example:** `"USD"`
</ParamField>

<ParamField body="chain" type="string" required>
  The chain the customer will pay on. See [GET /api/v1/tokens](/api-reference/tokens) for supported values.

  **Examples:** `"polygon"`, `"ethereum"`, `"bsc"`, `"tron"`, `"bitcoin"`
</ParamField>

<ParamField body="token" type="string">
  The token the customer will send. If omitted, the chain's native currency is used.

  **Examples:** `"USDT"`, `"USDC"`, `"ETH"`
</ParamField>

<ParamField body="description" type="string">
  Optional human-readable description stored with the invoice.

  **Example:** `"Order #1234 — 2x T-shirts"`
</ParamField>

<ParamField body="expiresInMinutes" type="number">
  Minutes until the invoice expires. If omitted, defaults to the platform rate window (15 minutes). Cannot exceed the platform rate window — values above the cap are silently reduced to the maximum.

  **Example:** `15`
</ParamField>

<ParamField body="webhookUrl" type="string">
  URL to receive webhook events for this payment. Must be a valid HTTPS URL. Overrides the default webhook URL set in merchant settings.

  **Example:** `"https://yoursite.com/webhooks/settlx"`
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs stored with the invoice. Returned in every webhook event — use it to correlate with your internal order ID.

  **Example:** `{ "orderId": "order_abc123", "userId": "user_456" }`
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="Payment object" defaultOpen>
    <ResponseField name="paymentId" type="string">
      Invoice UUID. Use this to correlate webhook events and to poll `GET /api/v1/invoices/:id/status`.
    </ResponseField>

    <ResponseField name="address" type="string">
      Deposit address to display to the customer. Do not reuse this address across invoices.
    </ResponseField>

    <ResponseField name="qrCode" type="string">
      Base64-encoded PNG QR code of the deposit address. Render with `<img src={data.qrCode} />`.
    </ResponseField>

    <ResponseField name="cryptoAmount" type="string">
      Exact amount the customer must send, with 8 decimal places (e.g. `"50.02000000"`).
    </ResponseField>

    <ResponseField name="cryptoCurrency" type="string">
      Token symbol the customer must send (e.g. `"USDT"`).
    </ResponseField>

    <ResponseField name="chain" type="string">
      Chain identifier (e.g. `"polygon"`).
    </ResponseField>

    <ResponseField name="fiatAmount" type="string">
      Original invoice amount in fiat (e.g. `"49.99000000"`).
    </ResponseField>

    <ResponseField name="fiatCurrency" type="string">
      Original invoice currency (e.g. `"USD"`).
    </ResponseField>

    <ResponseField name="exchangeRate" type="string">
      Exchange rate used for the fiat → crypto conversion at time of address generation.
    </ResponseField>

    <ResponseField name="status" type="string">
      Invoice status — always `"pending"` at creation.
    </ResponseField>

    <ResponseField name="expiresAt" type="string">
      ISO 8601 expiry timestamp. Always set — defaults to the platform rate window if not specified.
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 creation timestamp.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.settlx.io/api/v1/payments \
    -H "Authorization: Bearer pk_live_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "amount": "49.99",
      "currency": "USD",
      "chain": "polygon",
      "token": "USDT",
      "description": "Order #1234",
      "expiresInMinutes": 15,
      "webhookUrl": "https://yoursite.com/webhooks/settlx",
      "metadata": {
        "orderId": "order_abc123"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.settlx.io/api/v1/payments', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.SETTLX_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '49.99',
      currency: 'USD',
      chain: 'polygon',
      token: 'USDT',
      description: 'Order #1234',
      expiresInMinutes: 30,
      webhookUrl: `${process.env.BASE_URL}/webhooks/settlx`,
      metadata: { orderId: 'order_abc123' },
    }),
  });

  const { data } = await response.json();

  // Show to your customer
  console.log(data.address);       // Deposit address
  console.log(data.cryptoAmount);  // Exact amount to send
  console.log(data.qrCode);        // Base64 QR code — render as <img>
  ```

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

  client = httpx.Client(headers={"Authorization": "Bearer pk_live_your_api_key"})

  response = client.post("https://api.settlx.io/api/v1/payments", json={
      "amount": "49.99",
      "currency": "USD",
      "chain": "polygon",
      "token": "USDT",
      "description": "Order #1234",
      "expiresInMinutes": 15,
      "webhookUrl": "https://yoursite.com/webhooks/settlx",
      "metadata": {"orderId": "order_abc123"},
  })

  data = response.json()["data"]
  print(data["address"])       # Deposit address
  print(data["cryptoAmount"])  # Exact amount to send
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "data": {
      "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "address": "0xAbCdEf1234567890AbCdEf1234567890AbCdEf12",
      "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
      "cryptoAmount": "50.02000000",
      "cryptoCurrency": "USDT",
      "chain": "polygon",
      "fiatAmount": "49.99000000",
      "fiatCurrency": "USD",
      "exchangeRate": "1.00060",
      "status": "pending",
      "expiresAt": "2026-04-12T10:30:00.000Z",
      "createdAt": "2026-04-12T10:00:00.000Z"
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": "Bad Request",
    "message": "Chain polygon is not supported or not enabled"
  }
  ```

  ```json 401 theme={null}
  {
    "error": "Unauthorized",
    "message": "Invalid API key"
  }
  ```

  ```json 403 theme={null}
  {
    "error": "Forbidden",
    "message": "Merchant account is not active"
  }
  ```
</ResponseExample>

<Warning>
  The customer must send `cryptoAmount` of `cryptoCurrency` to `address`. A 1% tolerance is applied — amounts within 1% of the quoted value are accepted as full payment. Amounts below the tolerance threshold trigger partial payment handling.
</Warning>

<Note>
  Fulfill the order on `invoice.settled` — not `invoice.confirmed`. Confirmed means the chain accepted it; settled means funds have actually landed in your wallet.
</Note>