Become a Paddle partner
Join the Paddle partner program to read this content. You'll also get access to our partner API and agent tooling. Let us know a few details about your business to get started. Already a partner? Log in to view this page.
@paddle/partner-embeds embeds Paddle's hosted seller verification (KYB/KYC) flow into your application as a secure iframe.
The SDK creates the iframe, passes a token, prefills known fields, and surfaces lifecycle events. This is the recommended way to verify a seller.
The embed only renders on domains on Paddle's allowlist. Share your platform's domains with Paddle before you integrate.
Packages
| Package | Description |
|---|---|
@paddle/partner-embeds | Core SDK. Framework-agnostic iframe manager. |
@paddle/partner-embeds-react | React hooks wrapping the core SDK. |
Install
@paddle/partner-embeds
pnpm add @paddle/partner-embedsyarn add @paddle/partner-embedsnpm install @paddle/partner-embeds@paddle/partner-embeds-react
pnpm add @paddle/partner-embeds-reactyarn add @paddle/partner-embeds-reactnpm install @paddle/partner-embeds-reactEnvironments
The embed is served from the Paddle vendor domain (distinct from the API host):
| Environment | Base URL |
|---|---|
'production' (default) | https://vendors.paddle.com |
'sandbox' | https://sandbox-vendors.paddle.com |
PaddleVerification.create()
Use PaddleVerification.create() to create and mount the verification embed. In React, use the usePaddleVerification() hook instead. This takes the same options, except containerRef replaces target, and it mounts on mount and destroys on unmount automatically.
Parameters
targetstring | HTMLElement
Core SDK only. Selector or element to mount the iframe into. Required for the core SDK.
containerRefRefObject<HTMLElement | null>
React only. Ref to the container element. Required for
usePaddleVerification.tokenstring
Single-use token minted via the Partner API. Required.
environmentstring | null
Default:
productionWhich Paddle environment to load the embed from.
Values
productionLoad the embed fromvendors.paddle.com.sandboxLoad the embed fromsandbox-vendors.paddle.com.
themeobject | null
Visual theme of the embedded UI.
modestring
Light or dark mode. Applied at load for a zero-flash initial render.
Values
lightdark
prefillobject | null
Pre-populate form fields to shorten the flow for the seller.
countryCodestring
Example:
USISO country code.
annualRevenuestring
Revenue bracket.
Values
not_yet_live0_100k100k_500k500k_3m3m_10m
+ Show all values− Hide values
10m_plus
businessTypestring
Entity type.
Values
individualprivatepublic
productDescriptionstring
What the seller sells.
pricingPageUrlstring
Link to the seller's pricing page.
termsOfServiceUrlstring
Link to the seller's terms of service.
privacyPolicyUrlstring
Link to the seller's privacy policy.
refundPolicyUrlstring
Link to the seller's refund policy.
onReady() => void
Fires when the iframe has loaded and is interactive. Hide your spinner here.
onStepChange({ step: string; totalSteps?: number }) => void
Fires when the seller moves between steps. Use to build a progress bar.
onComplete({ id?: string }) => void
Fires when the seller submits their details for review — not when they're verified. Track the outcome by polling the verification.
onClose() => void
Fires when the seller dismisses the embed before completing.
onError({ code: string; message: string }) => void
Fires when an error occurs in the embed.
onResize({ height: number }) => void
Fires when the content height changes. The iframe auto-resizes.
Examples
import { PaddleVerification } from "@paddle/partner-embeds/verifications";
const verification = PaddleVerification.create({ target: "#verification-container", token, // single-use token minted via the Partner API 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} of ${totalSteps ?? "?"}`), onComplete: ({ id }) => console.log("Submitted for review:", id), onClose: () => console.log("User closed the verification"), onError: ({ code, message }) => console.error(`Error [${code}]:`, message),});
verification.mount();import { useRef } from "react";import { usePaddleVerification } from "@paddle/partner-embeds-react";
function VerificationForm({ token }: { token: string }) { const containerRef = useRef<HTMLDivElement>(null);
usePaddleVerification({ containerRef, token, environment: "sandbox", prefill: { countryCode: "US", annualRevenue: "100k_500k" }, onComplete: ({ id }) => console.log("Submitted for review:", id), onError: ({ code, message }) => console.error(code, message), });
// Render the container the embed mounts into: // return <div ref={containerRef} />;}The React hook returns { send } for pushing messages to 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. |
How the token flow works
- Mint a single-use code server-side by creating a magic session (
POST /magic-sessions/authorize) for the seller. - Pass the code to
PaddleVerification.create({ token }). - The SDK sends it to the iframe via
paddle:tokenafter thepaddle:readyhandshake. - Inside the frame, the single-use code is exchanged for a longer-lived session held in memory. Your platform never handles the long-lived credential.
postMessage protocol
The SDK manages a versioned postMessage protocol with origin validation. The envelope is { type, version, payload? }:
| Type | Direction | Purpose |
|---|---|---|
paddle:ready | iframe → parent | handshake; the iframe booted and is ready for the token. |
paddle:token | parent → iframe | the single-use token, sent after ready (not in the URL). |
paddle:theme | parent → iframe | runtime theme switch. |
paddle:prefill | parent → iframe | prefill payload pushed to the form. |
paddle:complete | iframe → parent | verification done → drives onComplete. |
paddle:error | iframe → parent | error → drives onError. |
Security model
The package is public, but the verification can only run on domains allowed by Paddle. If your domain isn't allowed, the iframe refuses to load, regardless of the SDK.
Contact your Paddle partner contact to get a domain added to the allowed list.
Theming
theme: { mode: 'light' | 'dark' }. The mode is applied at load for a zero-flash initial render, and paddle:theme handles runtime switches.