npm package: @paddle/partner-embeds
Description: SDK for partners to embed Paddle verification flows into their applications
Latest version: 1.1.1

# @paddle/partner-embeds

Core SDK for embedding Paddle flows (verification, etc.) into any web application via secure iframes. Framework-agnostic with zero runtime dependencies.

## Installation

```bash
npm install @paddle/partner-embeds
```

## Quick start

### Verification flow

```ts
import { PaddleVerification } from '@paddle/partner-embeds/verifications'

const verification = PaddleVerification.create({
  target: '#verification-container',
  token: 'vrf_token_...',
  environment: 'sandbox',
  prefill: {
    countryCode: 'US',
    annualRevenue: '100k_500k',
    productDescription: 'SaaS platform for project management',
  },
  theme: { mode: 'light' },
  onReady: () => console.log('Verification loaded'),
  onStepChange: ({ step, totalSteps }) => {
    console.log(`Step: ${step}${totalSteps ? ` of ${totalSteps}` : ''}`)
  },
  onComplete: ({ id }) => console.log('Verification complete:', id),
  onClose: () => console.log('User closed the verification'),
  onError: ({ code, message }) => console.error(`Error [${code}]:`, message),
})

verification.mount()
```

### Cleanup

When you're done with the embed, call `destroy()` to remove the iframe and clean up event listeners:

```ts
verification.destroy()
```

You can also temporarily remove and re-attach the embed without destroying it:

```ts
verification.unmount() // removes from DOM, keeps instance alive
verification.mount() // re-attaches
```

## API reference

### `PaddleVerification.create(options)`

Creates a verification embed instance.

#### Options

| Option        | Type                          | Required | Description                                           |
| ------------- | ----------------------------- | -------- | ----------------------------------------------------- |
| `target`      | `string \| HTMLElement`       | Yes      | CSS selector or DOM element to mount the iframe into. |
| `token`       | `string`                      | Yes      | Verification token obtained from the Paddle API.      |
| `environment` | `'production' \| 'sandbox'`   | No       | Defaults to `'production'`.                           |
| `theme`       | `{ mode: 'light' \| 'dark' }` | No       | Controls the visual theme of the embedded UI.         |
| `prefill`     | `VerificationPrefillPayload`  | No       | Pre-populate form fields (see below).                 |

#### Prefill options

| Field                | Type                                                                               | Description                             |
| -------------------- | ---------------------------------------------------------------------------------- | --------------------------------------- |
| `countryCode`        | `string`                                                                           | ISO country code (e.g. `'US'`, `'GB'`). |
| `annualRevenue`      | `'not_yet_live' \| '0_100k' \| '100k_500k' \| '500k_3m' \| '3m_10m' \| '10m_plus'` | Annual revenue bracket.                 |
| `businessType`       | `'individual' \| 'private' \| 'public'`                                            | Type of business entity.                |
| `productDescription` | `string`                                                                           | Description of the product being sold.  |
| `pricingPageUrl`     | `string`                                                                           | URL to the pricing page.                |
| `termsOfServiceUrl`  | `string`                                                                           | URL to terms of service.                |
| `privacyPolicyUrl`   | `string`                                                                           | URL to privacy policy.                  |
| `refundPolicyUrl`    | `string`                                                                           | URL to refund policy.                   |

#### Callbacks

##### `onReady`

```ts
onReady?: () => void
```

Fires when the iframe has loaded and is ready for interaction.

```ts
PaddleVerification.create({
  // ...
  onReady: () => {
    // Hide a loading spinner, reveal the container, etc.
    document.getElementById('loading')?.remove()
  },
})
```

##### `onStepChange`

```ts
onStepChange?: (payload: { step: string; totalSteps?: number }) => void
```

Fires when the user navigates between steps in the verification flow. Use this to build custom progress indicators or track how far users get.

```ts
PaddleVerification.create({
  // ...
  onStepChange: ({ step, totalSteps }) => {
    console.log(`Step: ${step}`)
    if (totalSteps) {
      progressBar.style.width = `${(parseInt(step) / totalSteps) * 100}%`
    }
  },
})
```

##### `onComplete`

```ts
onComplete?: (payload: { id?: string }) => void
```

Fires when the verification flow has been completed successfully. The `id` is the verification identifier.

```ts
PaddleVerification.create({
  // ...
  onComplete: ({ id }) => {
    // Redirect the user, update your backend, show a success message, etc.
    window.location.href = `/dashboard?verified=${id}`
  },
})
```

##### `onClose`

```ts
onClose?: () => void
```

Fires when the user closes or dismisses the verification flow before completing it.

```ts
PaddleVerification.create({
  // ...
  onClose: () => {
    // Show a message encouraging them to complete verification
    showBanner('You can resume verification at any time.')
  },
})
```

##### `onError`

```ts
onError?: (payload: { code: string; message: string }) => void
```

Fires when an error occurs within the embed. Use this for logging, displaying user-facing error messages, or triggering fallback behavior.

```ts
PaddleVerification.create({
  // ...
  onError: ({ code, message }) => {
    console.error(`Paddle verification error [${code}]: ${message}`)
    analytics.track('verification_error', { code, message })
  },
})
```

##### `onResize`

```ts
onResize?: (payload: { height: number }) => void
```

Fires when the embedded content changes height. The iframe is automatically resized, but you can use this callback if you need to adjust surrounding layout.

```ts
PaddleVerification.create({
  // ...
  onResize: ({ height }) => {
    console.log(`Embed height changed to ${height}px`)
  },
})
```

#### Instance methods

| Method      | Description                                                      |
| ----------- | ---------------------------------------------------------------- |
| `mount()`   | Attaches the iframe to the target element.                       |
| `unmount()` | Removes the iframe from the DOM without destroying the instance. |
| `destroy()` | Removes the iframe and cleans up all event listeners.            |

---

### `PaddleEmbed.create(options)` (advanced)

A lower-level API for embedding any Paddle flow. Use this when you need full control over the embed path and messaging.

```ts
import { PaddleEmbed } from '@paddle/partner-embeds'

const embed = PaddleEmbed.create({
  target: '#container',
  embedPath: '/embed/some-flow',
  params: { id: 'abc_123' },
  environment: 'sandbox',
  theme: { mode: 'dark' },
  onReady: () => console.log('Ready'),
  onError: ({ code, message }) => console.error(code, message),
  onResize: ({ height }) => console.log('Height:', height),
  onMessage: (msg) => console.log('Message:', msg),
})

embed.mount()
```

#### Options

| Option        | Type                          | Required | Description                                           |
| ------------- | ----------------------------- | -------- | ----------------------------------------------------- |
| `target`      | `string \| HTMLElement`       | Yes      | CSS selector or DOM element to mount the iframe into. |
| `embedPath`   | `string`                      | Yes      | Path to the embed flow (e.g. `'/embed/some-flow'`).   |
| `params`      | `Record<string, string>`      | No       | Query parameters appended to the embed URL.           |
| `environment` | `'production' \| 'sandbox'`   | No       | Defaults to `'production'`.                           |
| `theme`       | `{ mode: 'light' \| 'dark' }` | No       | Controls the visual theme.                            |

#### Callbacks

| Callback    | Payload                                                | Description                                     |
| ----------- | ------------------------------------------------------ | ----------------------------------------------- |
| `onReady`   | —                                                      | Fires when the iframe is loaded and ready.      |
| `onError`   | `{ code: string; message: string }`                    | Fires on errors within the embed.               |
| `onResize`  | `{ height: number }`                                   | Fires when the embedded content changes height. |
| `onMessage` | `{ type: string; version: string; payload?: unknown }` | Catch-all for any message from the iframe.      |

#### Instance methods

| Method          | Description                                                      |
| --------------- | ---------------------------------------------------------------- |
| `mount()`       | Attaches the iframe to the target element.                       |
| `unmount()`     | Removes the iframe from the DOM without destroying the instance. |
| `destroy()`     | Removes the iframe and cleans up all event listeners.            |
| `send(message)` | Sends a postMessage to the embedded iframe.                      |

## Environments

| Environment              | Base URL                             |
| ------------------------ | ------------------------------------ |
| `'production'` (default) | `https://vendors.paddle.com`         |
| `'sandbox'`              | `https://sandbox-vendors.paddle.com` |