Verification is how Paddle confirms an account is who they say they are before enabling live payments. It runs as a series of steps. First, Paddle checks the account holder's details and their business, then asks for anything else it needs along the way.
Use the API to read the state of a verification, so you can see where an account is in the verification process.
A verification entity holds information like:
- The overall
status, derived from the status of its steps. Use this as the headline state: when an account'sonboardingverification iscompleted, the account is ready for live payments. - The
verification_type, eitheronboardingfor account onboarding ordomainfor a domain review. An account has at most oneonboardingverification. - The
stepsthat make up the verification, each with its ownstatusandexpires_at.
Verifications are read-only. You can't create or update one using the API. Verification is completed by the account holder in the Paddle dashboard.
Verification only applies to live accounts. Sandbox accounts can take test payments as soon as they're created, so you don't need to check verifications in sandbox.
Accounts created before April 2024 may not have an onboarding verification. If an account went live before then, GET /verifications can return no verifications, or only domain verifications.
Verification status
Understand your overall verification status from the top-level status field. Paddle derives it from the underlying steps by priority, so it stays meaningful even as those steps change.
| Status | What it means |
|---|---|
pending | Verification hasn't started, or is waiting for its next step to start. |
in_progress | Paddle is running automated checks. Nothing is needed from the account holder. |
in_review | Paddle is reviewing the information provided by the account holder. |
action_required | Paddle needs something from the account holder before verification can continue. |
completed | Verification is complete. For an onboarding verification, the account is ready for live payments. |
failed | Verification didn't complete. |
To check whether an account is ready for live payments, list verifications with verification_type=onboarding and check the status of the verification that's returned. Don't rely on the first result of an unfiltered list. Results are newest first, so it's often a domain verification.
When status is action_required, the account holder can see what's needed and complete it in the Paddle dashboard.
Verification steps
The steps array shows how a verification is progressing. Steps use the same six status values as the verification itself, and each one has an expires_at date when the step lapses, or null if it never expires.
Paddle verifies an account using one of two flows, and picks one when account_setup is completed. On the automated flow, Paddle then replaces the steps after account_setup with a single automated_review step, so steps you saw earlier can disappear. This happens shortly after account_setup completes rather than at the same moment, so for a short time an account on the automated flow can still show the manual review steps.
To tell which flow an account is on, check whether its onboarding verification contains an automated_review step. Don't use domain verifications for this. Each one has its own automated_review step, whichever flow the account is on.
Automated review
| Step | Description |
|---|---|
account_setup | The account holder submits the prerequisite account details. |
automated_review | Paddle submits the business to a trusted partner for automated review. Where an account has no completed domain verification yet, this step stays pending until one completes. |
automated_review covers business identification and identity verification in a single step. Domain review runs separately, as a domain verification for each of the account's domains.
Manual review
| Step | Description |
|---|---|
account_setup | The account holder submits the prerequisite account details. |
domain_review | Paddle reviews the domain. |
business_identification | Paddle validates the business. Public companies and sole traders don't need this step. |
identity_verification | Paddle validates the stakeholders of the business. Public companies don't need this step. |
final_review | Paddle performs a manual review of the business. |
Which of the middle steps appear depends on the business, so don't assume all of them are present.
Steps are informational. Because the set of steps depends on the flow and the business, use the top-level status to determine your verification status rather than looking for a particular step.