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

# Widget SDK Quick Start

> Minimal embed with accurate types and amounts

<Info>
  This guide covers the smallest working integration. For every config option, see [Configuration reference](/widget-sdk/reference/configuration).
</Info>

## Prerequisites

<CardGroup cols={2}>
  <Card title="Paysight account" icon="user">
    An active merchant account with a configured product.
  </Card>

  <Card title="Product ID" icon="tag" href="https://app.paysight.io/management/products">
    A **numeric** product ID from the Paysight dashboard.
  </Card>

  <Card title="HTTPS" icon="lock">
    Production pages must use HTTPS.
  </Card>
</CardGroup>

## Steps

<Steps>
  <Step title="Load the SDK">
    ```html theme={null}
    <script src="https://payment.paysight.io/widget-sdk.js"></script>
    ```
  </Step>

  <Step title="Add a container">
    ```html theme={null}
    <div id="payment-container"></div>
    ```
  </Step>

  <Step title="Initialize the widget">
    ```javascript theme={null}
    const widget = PaySightSDK.createWidget({
      targetId: 'payment-container',
      config: {
        productId: YOUR_PRODUCT_ID,
        sessionId: 'YOUR_SESSION_ID',
        environment: 'sandbox',
        amount: 29.99,
        customer: {
          email: 'customer@example.com',
          firstName: 'Jane',
          lastName: 'Doe',
          country: 'US',
          state: 'CA',
        },
        fields: [
          {
            label: 'Email',
            placeholder: 'you@example.com',
            fieldType: 'email',
            position: 'above',
            size: 'full',
          },
        ],
      },
      onReady: () => console.log('Widget ready'),
      onMessage: (message) => {
        switch (message.type) {
          case 'PAYMENT_SUCCESS':
            console.log('Paid', message.payload);
            break;
          case 'PAYMENT_ERROR':
            console.error(message.payload);
            break;
        }
      },
    });
    ```
  </Step>
</Steps>

## Customer object vs fields

These serve different purposes:

| Option     | Purpose                                                                                                                                          |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `customer` | **Optional prefill** — seeds values into the form or payment request. Omit fields you want the shopper to enter.                                 |
| `fields`   | **Required form layout** — defines which inputs appear in the iframe. Your product typically requires a minimum set (e.g. email, name, country). |

<Callout type="warning">
  `customer` alone does not replace `fields`. If you omit `fields`, the widget uses your product's default field requirements. If required data is missing at submit time, you receive `ERROR` with `VALIDATION_FAILED`.
</Callout>

Example — prefill email but still show the field:

```javascript theme={null}
customer: { email: 'customer@example.com', country: 'US' },
fields: [
  { label: 'Email', placeholder: 'you@example.com', fieldType: 'email', position: 'above', size: 'full' },
  { label: 'Country', placeholder: 'Select country', fieldType: 'country', position: 'above', size: 'half' },
],
```

See [Configuration guide](/widget-sdk/guides/configuration) for semi-required customer data.

## Important types

| Field              | Type                        | Notes                                            |
| ------------------ | --------------------------- | ------------------------------------------------ |
| `productId`        | `number`                    | Not a string                                     |
| `amount`           | `number`                    | Decimal major units (`29.99`), not cents         |
| `environment`      | `'sandbox' \| 'production'` | Use `sandbox` for testing, `production` for live |
| `customer.country` | `string`                    | Two-letter ISO code, often required              |
| `fields`           | `FieldConfig[]`             | Array with `fieldType`, `position`, `size`       |

## Optional: Wallet-only checkout

If you enable **Apple Pay** and/or **Google Pay**, set `showOnlyWalletMethods: true` to hide the card form when a wallet is available, with automatic fallback to the full card UI.

<CardGroup cols={2}>
  <Card title="Wallet-only checkout" icon="wallet" href="/widget-sdk/guides/wallet-only-checkout">
    Requirements, layout, fallbacks, and examples.
  </Card>

  <Card title="Apple Pay via Widget" icon="mobile" href="/widget-sdk/guides/apple-pay-via-widget">
    Domain verification and parent-hosted Apple Pay.
  </Card>
</CardGroup>

## Try it live

<CardGroup cols={2}>
  <Card title="Open playground" icon="play" href="https://payment.paysight.io/demo?preset=basic">
    Interactive sandbox — edit config, watch events, copy embed code.
  </Card>

  <Card title="Playground guide" icon="book-open" href="/widget-sdk/guides/playground">
    Walkthrough of all 12 presets and inspector tabs.
  </Card>
</CardGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/widget-sdk/guides/configuration">
    Customer prefill, fields, and full setup
  </Card>

  <Card title="Events" icon="bell" href="/widget-sdk/reference/events">
    Handle payment, 3DS, and cart events
  </Card>

  <Card title="External button" icon="hand-pointer" href="/widget-sdk/guides/external-payment-button">
    Host your own pay CTA
  </Card>

  <Card title="Upsell flow" icon="arrow-right" href="/widget-sdk/guides/saved-payment-and-upsell">
    Two-page saved-payment checkout
  </Card>
</CardGroup>