@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

npm install @paddle/partner-embeds

Quick start

Verification flow

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:

verification.destroy()

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

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

onReady?: () => void

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

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

onStepChange

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.

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

onComplete

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

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

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

onClose

onClose?: () => void

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

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

onError

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.

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

onResize

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.

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.

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 |