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

# JS SDK

<div className="Goal">
  ## Push JS SDK Reference

  The SDK must be loaded as a script tag on your website — it cannot be statically bundled via package management.

  ```html theme={null}
  <script src="https://cdn.pushcash.com/sdk/push.umd.js"></script>
  ```
</div>

<Note>
  The SDK is loaded from `cdn.pushcash.com` and creates iframes that load content from the same origin. If your site uses a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP), ensure the following directives include `https://cdn.pushcash.com`:

  * `script-src` — to load the SDK script
  * `frame-src` — to allow the widget iframes
</Note>

## Widget

### `new window.PushCash.Widget(options)`

Creates the Push User Widget. The widget renders a card input form into the container specified by `selector`.

#### Options (`WidgetOptions`)

| Field          | Type         | Required | Description                                                                              |
| -------------- | ------------ | :------: | ---------------------------------------------------------------------------------------- |
| `url`          | `string`     |     ✅    | URL returned from [create-user-url](./apireference/user/create-user-url).                |
| `selector`     | `string`     |     ✅    | CSS selector for the container element to render into.                                   |
| `onValid`      | `() => void` |     ❌    | Called once the widget has received valid card details. Use to enable the submit button. |
| `background`   | `string`     |     ❌    | Widget background (CSS color value).                                                     |
| `fontSize`     | `string`     |     ❌    | Base font size (CSS value, e.g. `14px`).                                                 |
| `borderRadius` | `string`     |     ❌    | Corner radius (CSS value, e.g. `12px`).                                                  |
| `padding`      | `string`     |     ❌    | Inner padding (CSS value, e.g. `16px`).                                                  |
| `color`        | `string`     |     ❌    | Text color (CSS color value).                                                            |

#### Returns

A `Widget` instance.

#### Example

```js theme={null}
const widget = new window.PushCash.Widget({
  url: 'https://cdn.pushcash.com/widget/?param=1&param=2',
  selector: '#payment-container',
  onValid: () => { console.log('user has provided valid card details') },
  background: '#ffffff',
  fontSize: '16px',
  borderRadius: '8px',
  padding: '12px',
  color: '#000000',
});
```

### `widget.tokenize()`

Generates a token from the user’s card details which can be used to process a transaction by calling [authorize-payment](./apireference/authorization/authorize-payment). Throws an error if the user has not provided valid card details.

#### Signature

```ts theme={null}
tokenize: () => Promise<{ token: string }>
```

#### Example

```js theme={null}
try {
  const { token } = await widget.tokenize();
} catch (error) {
  console.error(‘User has not provided valid card details:’, error);
}
```

### `widget.destroy()`

Unmounts the widget and cleans up resources.

#### Signature

```ts theme={null}
destroy: () => void
```

***

## Apple Pay Launcher

### `new window.PushCash.ApplePay(config)`

Creates an Apple Pay launcher instance.

#### Parameters

| Field | Type     | Required | Description                                                                                                                             |
| ----- | -------- | :------: | --------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | `string` |     ✅    | URL returned from [create-user-url](./apireference/user/create-user-url) with `type: "apple_pay"`. Must be newly created per page load. |

#### Example

```js theme={null}
const launcher = new window.PushCash.ApplePay({
  url: '<your-url>',
});
```

### `launcher.display(args)`

Launches the Apple Pay payment sheet and runs the Apple Pay flow.

#### Parameters

| Field         | Type                                                   | Required | Description                                                                                                                                                                                                                                                                                                                         |
| ------------- | ------------------------------------------------------ | :------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`      | `number`                                               |     ✅    | Payment amount in **cents** (must be > 0).                                                                                                                                                                                                                                                                                          |
| `direction`   | `'cash_in'`                                            |     ✅    | Only `cash_in` is supported.                                                                                                                                                                                                                                                                                                        |
| `currency`    | `'USD'`                                                |     ✅    | Only `"USD"` is supported.                                                                                                                                                                                                                                                                                                          |
| `onAuthorize` | `(token: string) => Promise<'approved' \| 'declined'>` |     ✅    | Called after the user authorizes payment in the Apple Pay sheet. Receives a `token` which must be passed to [authorize payment](./apireference/authorization/authorize-payment). Must return `'approved'` or `'declined'` based on the authorization result. The amount and currency must match the values provided to `display()`. |
| `onComplete`  | `() => void \| Promise<void>`                          |     ❌    | Called when the Apple Pay session completes.                                                                                                                                                                                                                                                                                        |

#### Example

```js theme={null}
launcher.display({
  amount: 1000,
  direction: 'cash_in',
  currency: 'USD',
  onAuthorize: async (token) => {
    // call backend to authorize payment via Push API
    // pass token to POST /authorize
    const result = await yourBackend.authorize(token);
    return result.status; // 'approved' or 'declined'
  },
  onComplete: () => {
    // handle session completion
  },
});
```