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

# API reference

> PaySightSDK.createWidget and widget instance methods

## `PaySightSDK.createWidget`

```typescript theme={null}
const widget = PaySightSDK.createWidget({
  targetId: string;
  config: WidgetConfig;
  onReady?: () => void;
  onError?: (error: Error) => void;
  onMessage?: (message: WidgetMessage) => void;
  minHeight?: number;
  iframeId?: string;
  applePayContainerId?: string;   // default: 'apple-pay-slot'
  googlePayContainerId?: string;  // default: 'google-pay-slot'
});
```

### Returns

| Method               | Description                                             |
| -------------------- | ------------------------------------------------------- |
| `update(updates)`    | Merge partial config at runtime                         |
| `submitPayment()`    | Trigger card/wallet checkout                            |
| `submitUpsell()`     | Trigger upsell charge (`usePreviousPaymentMethod` mode) |
| `subscribe(handler)` | Add `onMessage` listener; returns unsubscribe function  |
| `destroy()`          | Tear down iframe and listeners                          |

### `submitPayment` / `submitUpsell`

Use when `hidePaymentButton: true` or when you want a host-controlled CTA.

```javascript theme={null}
document.getElementById('pay-btn').onclick = () => widget.submitPayment();
document.getElementById('upsell-btn').onclick = () => widget.submitUpsell();
```

<Callout type="info">
  Calling `submitPayment()` during upsell mode (or `submitUpsell()` during checkout) emits `ERROR` with code `INVALID_MODE`.
</Callout>

### `update`

```javascript theme={null}
widget.update({
  singlePurchase: true,
  amount: 39.99,
  customer: { email: 'new@example.com' },
});
```

Config updates are sent to the iframe as `CONFIG_UPDATE`. Listen for `CONFIG_UPDATE_SUCCESS`.

### `subscribe`

```javascript theme={null}
const unsubscribe = widget.subscribe((msg) => {
  if (msg.type === 'PAYMENT_SUCCESS') handleSuccess(msg.payload);
});
// later: unsubscribe();
```

## CDN script

```html theme={null}
<script src="https://payment.paysight.io/widget-sdk.js"></script>
```

Global: `PaySightSDK.createWidget`.

Use `environment: 'sandbox'` or `environment: 'production'` in config to target the matching widget endpoint.

## Related

* [Configuration reference](/widget-sdk/reference/configuration)
* [External payment button](/widget-sdk/guides/external-payment-button)
* [Error codes](/widget-sdk/reference/error-codes)