Verify a seller and go-live

The last stage of go-live is KYB/KYC verification. You collect the seller's details with the verification embed, then Paddle reviews them automatically. When a seller passes, Paddle enables live payments on their account and you can take them live.

Verification runs asynchronously, so the seller can keep iterating on their app while it completes. Most of the work on your side is surfacing the status and guiding the seller through anything Paddle asks for.

How it works

Your platform should surface verification status and guide sellers through the process, polling the partner API for verification details. You can use the @paddle/partner-embeds library to start verification.

sequenceDiagram
    participant P as Your platform
    participant SDK as partner-embeds
    participant IF as Paddle embed
    participant API as Partner API
    P->>API: Authorize magic session
    API-->>P: one-time code
    P->>SDK: PaddleVerification.create({ token, prefill })
    SDK->>IF: Load embed
    Note over IF: Seller completes<br>account setup
    IF-->>P: onComplete (submitted for review)
    P->>API: Poll GET /seller-verifications/{id}
    API-->>P: automated_review status
    Note over P: Surface status,<br>handle any actions

Overview

Verify a seller in four steps:

1. Open the verification embed
   Drop Paddle's hosted verification flow into your app and let the seller submit their details.
2. Present verification status
   Poll the seller's verification and show its status in your platform.
3. Handle verification next steps
   Surface any actions Paddle needs from the seller to finish verifying.
4. Take the seller live When verification passes, switch the seller's app to live and let them accept real payments.

Open the verification embed

Layer

Your platform

Authentication

User API key

Environment

Live

The @paddle/partner-embeds SDK renders Paddle's hosted verification flow inside your app as a secure iframe. You mint a token, pass it to the embed with anything you can prefill, and the seller completes a short set of steps.

Install

Install @paddle/partner-embeds or @paddle/partner-embeds-react using your package manager:

pnpm add @paddle/partner-embeds

yarn add @paddle/partner-embeds

npm install @paddle/partner-embeds

Mint a token

Send a request to the POST /magic-sessions/authorize endpoint, using the user API key as a bearer token. The body is empty. You only need to do this for live.

If successful, Paddle returns a 201 with a one-time-use code. Pass this to the embed as its token in the next step. You don't need to cache it.

{
  "data": {
    "code": "Vh7nQ2pXk9Lm4Rt1Ws8Yz6Bc3Nj0Gd5Fu2Ei7Ol4KaZ",
    "expires_at": "2026-03-05T19:21:36.711613073Z"
  },
  "meta": {
    "request_id": "d1f2a3b4-5c6d-47e8-9f0a-1b2c3d4e5f60"
  }
}

Open a verification embed

Pass the token you generated to PaddleVerification.create to open the verification flow.

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

PaddleVerification.create({
  target: '#verification',
  token,                              // the one-time code from POST /magic-sessions/authorize
  environment: 'production',
  prefill: { countryCode: 'US', businessType: 'private' },
  onComplete: ({ id }) => {
    // The seller has submitted their details for review — not yet verified.
    // Refresh the verification status in your UI.
  },
  onError: ({ code, message }) => console.error(code, message),
}).mount()

We recommend prefilling any information you have about the seller to make this process as quick as possible. For example, you can prefill a seller's name, country, business type, and the policy URLs your agent generated.

See the embed SDK reference for the full API, the React hook, and theming.

Get and store the verification ID

When a seller completes the verification flow, onComplete fires and returns an ID. You can also get a seller verification by calling the GET /seller-verifications endpoint.

{
  "data": [
    {
      "id": "slrvrf_01gjn16x6xxb6vkznqwfphthxb",
      "seller_id": "sel_01jqx8k5z9r2m4n6p8s0t2v4w6",
      "verification_type": "onboarding",
      "steps": [
        {
          "id": "slrvrfstp_01h2m3n4p5q6r7s8t9v0w1x2y3",
          "key": "account_setup",
          "status": "completed",
          "expires_at": null,
          "created_at": "2026-06-30T09:30:00.000Z",
          "updated_at": "2026-06-30T09:48:00.000Z"
        },
        {
          "id": "slrvrfstp_01h2m3n4p5q6r7s8t9v0w1x2z4",
          "key": "automated_review",
          "status": "in_progress",
          "expires_at": null,
          "created_at": "2026-06-30T09:48:00.000Z",
          "updated_at": "2026-06-30T09:48:00.000Z"
        }
      ],
      "created_at": "2026-06-30T09:30:00.000Z",
      "updated_at": "2026-06-30T09:48:00.000Z"
    }
  ],
  "meta": {
    "request_id": "43fbc4d5-6e7f-4081-9c93-bd2e3f405162"
  }
}

Extract the seller verification ID (prefixed slrvrf_) and store it against the seller in your database. You need this to present details about a seller's verification process in your platform.

Present verification status

Layer

Your platform

Authentication

Partner API key

Environment

Live

After a seller has been through the initial verification flow, Paddle starts verifying the seller's account. Verification is a multi-step process where Paddle checks a seller is who they say they are, and that their business details are valid. This verification step is called automated_review.

You should present details of a seller's verification status in your dashboard by polling the GET /seller-verifications/{seller_verification_id} endpoint. You only need to do this for live.

If successful, Paddle returns a 200 with the seller verification. Find the step with key: automated_review in the steps array and use its status to drive your UI.

{
  "data": {
    "id": "slrvrf_01gjn16x6xxb6vkznqwfphthxb",
    "seller_id": "sel_01jqx8k5z9r2m4n6p8s0t2v4w6",
    "verification_type": "onboarding",
    "steps": [
      {
        "id": "slrvrfstp_01h2m3n4p5q6r7s8t9v0w1x2y3",
        "key": "account_setup",
        "status": "completed",
        "expires_at": null,
        "created_at": "2026-06-30T09:30:00.000Z",
        "updated_at": "2026-06-30T09:48:00.000Z"
      },
      {
        "id": "slrvrfstp_01h2m3n4p5q6r7s8t9v0w1x2z4",
        "key": "automated_review",
        "status": "in_review",
        "expires_at": null,
        "created_at": "2026-06-30T09:48:00.000Z",
        "updated_at": "2026-06-30T09:52:00.000Z"
      }
    ],
    "created_at": "2026-06-30T09:30:00.000Z",
    "updated_at": "2026-06-30T09:52:00.000Z"
  },
  "meta": {
    "request_id": "54acd5e6-7f80-4192-8da4-ce3f40516273"
  }
}

Map the automated_review step's status to clear copy for the seller:

Poll while a step is in_progress or action_required, around every 60 seconds while the seller is on the verification screen, backing off when they navigate away. You can also provide a refresh button, so sellers can manually refresh their verification status.

Handle verification next steps

Layer

Your platform

Authentication

Partner API key

Environment

Live

Verifications typically go to action_required rather than completed immediately. The most common next step is asking the seller to verify their identity using their government-issued ID.

When automated_review.status is action_required, read the step from the GET /seller-verifications/{seller_verification_id}/steps/automated-review endpoint and surface the next step for the seller. You only need to do this for live.

{
  "data": {
    "id": "slrvrfstp_01h2m3n4p5q6r7s8t9v0w1x2z4",
    "key": "automated_review",
    "status": "action_required",
    "status_reason": "sole_trader_external_url_check",
    "required_actions": [],
    "stakeholders": [
      {
        "id": "stkhdr_01h6a7b8c9d0e1f2g3h4j5k6m7",
        "role": "owner",
        "first_name": "Sam",
        "last_name": "Taylor",
        "email": "sam@acme.com",
        "date_of_birth": "1990-01-01",
        "required_actions": [
          {
            "id": "slrvrfrac_01h7n8p9q0r1s2t3v4w5x6y7z8",
            "type": "external_url_check",
            "status": "not_started",
            "details": {
              "url": "https://verify.example.com/session/abc-123",
              "expires_at": "2026-07-07T09:52:00.000Z"
            }
          }
        ]
      }
    ],
    "files": [],
    "expires_at": null,
    "created_at": "2026-06-30T09:48:00.000Z",
    "updated_at": "2026-06-30T09:52:00.000Z"
  },
  "meta": {
    "request_id": "65bde6f7-8091-42a3-9eb5-df405162738a"
  }
}

Use the status_reason of the automated review step to present the next step:

Continue to poll every 60 seconds while a step is in_progress or action_required. Once the action is done and Paddle finishes its review, automated_review settles on completed or failed.

External URL check

When sole traders and stakeholders have to complete an identity check, Paddle returns a URL for each person where they can upload their government-issued ID and confirm their details. This is handled securely by one of our third-party providers.

In your platform UI:

• For sole_trader_external_url_check, present users with a single button that says "Verify identity" and takes them to details.url.
• For stakeholders_external_url_check, present a list of stakeholders and a link to their identity verification. Rather than a button, we recommend showing a list of links that users can quickly copy, so they can send to the relevant stakeholders.

Upload file

For security, file uploads are handled in the Paddle dashboard. Generate a magic link that logs the seller in and takes them straight to the page where they upload the requested documents.

First, mint a magic session: send a request to the POST /magic-sessions/authorize endpoint, using the user's API key as a bearer token. The body is empty. You only need to do this for live.

If successful, Paddle returns a 201 with a one-time-use code.

{
  "data": {
    "code": "Vh7nQ2pXk9Lm4Rt1Ws8Yz6Bc3Nj0Gd5Fu2Ei7Ol4KaZ",
    "expires_at": "2026-03-05T19:21:36.711613073Z"
  },
  "meta": {
    "request_id": "d1f2a3b4-5c6d-47e8-9f0a-1b2c3d4e5f60"
  }
}

Extract the code, then construct a magic link by passing it to the code query param and adding redirect=onboarding. For example:

https://vendors.paddle.com/magic-sessions/login?code=Vh7nQ2pXk9Lm4Rt1Ws8Yz6Bc3Nj0Gd5Fu2Ei7Ol4KaZ&redirect=onboarding

Send the seller to this URL. They're logged into the dashboard automatically and land on the onboarding page to upload the requested documents.

See Generate authenticated links to the Paddle dashboard for the full magic-link reference.

Take the seller live

Layer

Your platform

Environment

Live

When automated_review.status is completed, verification is complete. Paddle enables checkout on the seller's live account, and they can start taking real payments.

There's no separate activate or go-live call required, but we recommend giving the seller a clear go-live moment in your platform UI. For example, a readiness state that reflects their verification status, and a "Go live" control that switches on live payments. Keep a test/live toggle so they can still preview in sandbox afterward.

When a seller goes live, use your agent to switch their app from sandbox to live. Use the seller's live API keys and client-side tokens, and resolve prices against their live catalog.