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

# Get Invoice Status

> Public polling endpoint for invoice payment status

# Get Invoice Status

Public endpoint for polling invoice payment status. Designed for use on the customer-facing checkout page as a fallback when the WebSocket connection is unavailable.

This endpoint does **not** require authentication.

<Note>
  Prefer the WebSocket at `/ws/invoices/:id` for real-time updates. Use this endpoint only as a polling fallback. Recommended polling interval: 5–10 seconds.
</Note>

## Path Parameters

<ParamField path="id" type="string" required>
  UUID of the invoice.
</ParamField>

## Response

<ResponseField name="data" type="object">
  <Expandable title="Invoice status object" defaultOpen>
    <ResponseField name="id" type="string">UUID of the invoice</ResponseField>

    <ResponseField name="status" type="string">
      Invoice status. One of: `pending`, `partial`, `confirmed`, `settled`, `expired`.
    </ResponseField>

    <ResponseField name="amount" type="string">Original invoice amount</ResponseField>
    <ResponseField name="currency" type="string">Original invoice fiat currency (e.g. `USD`)</ResponseField>
    <ResponseField name="description" type="string | null">Invoice description</ResponseField>
    <ResponseField name="merchantName" type="string">Merchant display name (for branding the checkout page)</ResponseField>
    <ResponseField name="confirmations" type="number">Current on-chain confirmation count for the latest detected payment</ResponseField>
    <ResponseField name="requiredConfirmations" type="number">Confirmations required for the payment chain</ResponseField>

    <ResponseField name="paymentStatus" type="string">
      Combined status string for UI rendering. One of: `pending`, `detected`, `confirmed`, `partial`, `wrong_token`, `settled`, `expired`.
    </ResponseField>

    <ResponseField name="paymentStatusDetail" type="string | null">
      Latest payment record's status — `detected` or `confirmed`. `null` if no payment yet.
    </ResponseField>

    <ResponseField name="settledAmount" type="string | null">Net amount delivered in settlement, if completed</ResponseField>

    <ResponseField name="txHash" type="string | null">
      Latest on-chain transaction hash — payment hash if detected, settlement hash if settled.
    </ResponseField>

    <ResponseField name="expiresAt" type="string | null">ISO 8601 expiry timestamp</ResponseField>
    <ResponseField name="createdAt" type="string">ISO 8601 creation timestamp</ResponseField>

    <ResponseField name="returnUrl" type="string | null">
      Post-payment return URL extracted from invoice metadata (`returnUrl`, `successUrl`, etc.). `null` if not set.
    </ResponseField>

    <ResponseField name="totalReceivedAmount" type="string">Cumulative amount received (across multiple payments) in payment currency</ResponseField>
    <ResponseField name="totalReceivedCurrency" type="string">Currency of received payments</ResponseField>
    <ResponseField name="remainingAmount" type="string">Amount still owed (8-decimal string)</ResponseField>
    <ResponseField name="paymentProgress" type="number">Progress 0–100 (integer percent)</ResponseField>
    <ResponseField name="hasDetectedPayment" type="boolean">Whether at least one non-mismatch payment has been detected</ResponseField>
    <ResponseField name="detectedPaymentAmount" type="string | null">Amount of the most recent detected payment</ResponseField>
    <ResponseField name="detectedPaymentCurrency" type="string | null">Currency of the most recent detected payment</ResponseField>

    <ResponseField name="paymentIssueType" type="string | null">
      Issue type if any: `underpaid`, `overpaid`, or `wrong_token`. `null` if none.
    </ResponseField>

    <ResponseField name="mismatchPayment" type="object | null">
      Set when a customer paid the wrong token. Contains `amount`, `currency`, `actualCurrency`, `txHash`. `null` if no mismatch.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.settlx.io/api/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status
  ```

  ```javascript Browser polling theme={null}
  async function pollInvoiceStatus(invoiceId) {
    const response = await fetch(`https://api.settlx.io/api/v1/invoices/${invoiceId}/status`);
    const { data } = await response.json();

    if (data.status === 'settled') {
      redirectToSuccess(data.returnUrl);
      return;
    }

    if (data.status === 'expired') {
      showExpiredUI();
      return;
    }

    // Still pending — show progress and poll again
    updateProgressBar(data.paymentProgress);
    if (data.hasDetectedPayment) {
      showAwaitingConfirmationsUI(data.confirmations, data.requiredConfirmations);
    }

    setTimeout(() => pollInvoiceStatus(invoiceId), 5000);
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 (pending — no payment yet) theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "pending",
      "amount": "49.99",
      "currency": "USD",
      "description": "Order #1234",
      "merchantName": "Acme Inc",
      "confirmations": 0,
      "requiredConfirmations": 0,
      "paymentStatus": "pending",
      "paymentStatusDetail": null,
      "settledAmount": null,
      "txHash": null,
      "expiresAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "returnUrl": null,
      "totalReceivedAmount": "0",
      "totalReceivedCurrency": "USD",
      "remainingAmount": "49.99000000",
      "paymentProgress": 0,
      "hasDetectedPayment": false,
      "detectedPaymentAmount": null,
      "detectedPaymentCurrency": null,
      "paymentIssueType": null,
      "mismatchPayment": null
    }
  }
  ```

  ```json 200 (detected — awaiting confirmations) theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "pending",
      "amount": "49.99",
      "currency": "USD",
      "description": "Order #1234",
      "merchantName": "Acme Inc",
      "confirmations": 4,
      "requiredConfirmations": 12,
      "paymentStatus": "detected",
      "paymentStatusDetail": "detected",
      "settledAmount": null,
      "txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
      "expiresAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "returnUrl": null,
      "totalReceivedAmount": "0",
      "totalReceivedCurrency": "USDT",
      "remainingAmount": "49.99000000",
      "paymentProgress": 0,
      "hasDetectedPayment": true,
      "detectedPaymentAmount": "49.99",
      "detectedPaymentCurrency": "USDT",
      "paymentIssueType": null,
      "mismatchPayment": null
    }
  }
  ```

  ```json 200 (settled) theme={null}
  {
    "data": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": "settled",
      "amount": "49.99",
      "currency": "USD",
      "description": "Order #1234",
      "merchantName": "Acme Inc",
      "confirmations": 12,
      "requiredConfirmations": 12,
      "paymentStatus": "settled",
      "paymentStatusDetail": "confirmed",
      "settledAmount": "48.74",
      "txHash": "0x9f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c3a8b7e6d5f4c",
      "expiresAt": "2024-01-15T10:30:00.000Z",
      "createdAt": "2024-01-15T10:00:00.000Z",
      "returnUrl": "https://yoursite.com/order/1234/success",
      "totalReceivedAmount": "49.99",
      "totalReceivedCurrency": "USDT",
      "remainingAmount": "0.00000000",
      "paymentProgress": 100,
      "hasDetectedPayment": true,
      "detectedPaymentAmount": "49.99",
      "detectedPaymentCurrency": "USDT",
      "paymentIssueType": null,
      "mismatchPayment": null
    }
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Not Found",
    "message": "Invoice not found"
  }
  ```
</ResponseExample>

<Warning>
  This endpoint is **public** — anyone with the invoice ID can poll it. Do not include the invoice ID in URLs that customers can bookmark and share with third parties if you consider the metadata sensitive.
</Warning>