{"registry_version":"2026.1025.387","generated_at":"2026-10-25T06:27:00Z","content_sha256":"089d16f627d9365e3d0663cc8069203706d7cb23a76c332226e29686968811a5","signed":true,"signature":{"key_id":"ed25519:74ca19268e364242","algorithm":"ed25519","expires_at":"2026-11-24T06:27:09Z","expired":false,"manifest":"/registry/manifest.json"},"id":"paddle/billing-api","name":"Paddle Billing API","vendor":"Paddle","status":"researched","last_verified":null,"last_researched":"2026-10-25","summary":"Merchant-of-record billing for software and SaaS. Build in a separate sandbox account, then verify the live account (domain review, business and identity checks) before taking live payments. Server-side API keys, client-side tokens for Paddle.js, and per-destination webhook secrets.","account_model":{"summary":"Sandbox and live are separate Paddle accounts with separate logins, catalogs, API keys, client-side tokens and webhook destinations.","accounts":[{"name":"Paddle sandbox account","kind":"developer","owned_by":"the person or business","required":true,"note":"No verification needed; domains auto-approved."},{"name":"Paddle live account","kind":"organisation","owned_by":"the business (or sole proprietor)","required":true,"note":"Must be verified before live payments."}],"notes":["Paddle recommends starting live verification early because it can take days and cannot be skipped [to verify exact wording]."]},"prerequisites":[{"need":"A software or SaaS product that fits Paddle's Acceptable Use Policy","note":"Physical goods and human services unrelated to software are prohibited."},{"need":"A live HTTPS website on the checkout domain with product description, pricing, terms (with the legal brand name), privacy policy and refund policy reachable from navigation, and a contact method"}],"identity_requires":[],"have_ready":[{"kind":"live_website","description":"Live HTTPS website with description, pricing, terms and conditions, refund policy, privacy policy and contact details.","why":"Domain review checks these; only approved domains can host live checkout.","needed_for":["domain_review"],"auto_check":"website_live","source_url":"https://www.paddle.com/help/start/account-verification/what-is-domain-verification"},{"kind":"other","description":"Personal details (date of birth, home address) and the business legal name and address.","why":"Live account setup asks for them.","needed_for":["live_account_setup"],"auto_check":"none","source_url":"https://developer.paddle.com/build/set-up-checklist/"},{"kind":"government_id","description":"Government-issued ID, if Paddle's identity verification asks for it.","why":"Identity verification is a phase of account verification; the document requirement was not confirmed on an official page [to verify].","needed_for":["live_account_setup"],"auto_check":"none","source_url":"https://www.paddle.com/help/start/account-verification"},{"kind":"bank_account","description":"Bank account for payouts [to verify where in the flow this is asked].","why":null,"needed_for":[],"auto_check":"none","source_url":null}],"steps":[{"id":"sandbox_signup","title":"Sign up for a sandbox account","summary":"The person creates a Paddle sandbox account (separate from live) to build and test.","route":"guided","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":[],"optional":false,"url":"https://sandbox-vendors.paddle.com/signup","lead_time":null,"preflight":[],"captures":null},{"id":"sandbox_api_key","title":"Create a sandbox API key","summary":"In Settings > Authentication > API keys, create a key with a name, minimal permissions and an expiry. It is shown once.","route":"copilot","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":["sandbox_signup"],"optional":false,"url":"https://sandbox-vendors.paddle.com","lead_time":null,"preflight":[],"captures":"PADDLE_API_KEY_SANDBOX"},{"id":"sandbox_client_token","title":"Create a sandbox client-side token","summary":"Create a client-side token for Paddle.js (starts test_). Safe for the frontend; never put an API key in the frontend.","route":"copilot","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":["sandbox_signup"],"optional":false,"url":"https://sandbox-vendors.paddle.com","lead_time":null,"preflight":[],"captures":"NEXT_PUBLIC_PADDLE_CLIENT_TOKEN_SANDBOX"},{"id":"live_signup","title":"Sign up for the live account","summary":"The person creates the live Paddle account. Start this early, because verification takes time.","route":"guided","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":[],"optional":false,"url":"https://vendors.paddle.com/signup","lead_time":null,"preflight":[],"captures":null},{"id":"domain_review","title":"Submit the website domain for approval","summary":"Under Settings > Website approval, submit each domain or subdomain that will host checkout.","route":"copilot","gate":"third_party_review","human_only":true,"gate_label":"The provider reviews it","depends_on":["live_signup"],"optional":false,"url":"https://vendors.paddle.com","lead_time":{"official":{"text":"Most submissions are approved automatically; manual reviews are typically completed within an estimated 5-7 business days.","source_url":"https://www.paddle.com/help/start/account-verification/what-is-domain-verification","source_title":"Domain Review (Paddle Help Center)"},"reported":null,"typical_minutes":null},"preflight":["website_live","website_not_form_only","privacy_policy_reachable"],"captures":null},{"id":"live_account_setup","title":"Complete account setup and business verification","summary":"Enter personal details, business legal name and address, website and offering, then finish anything else Paddle asks for (such as documents or identity checks). Paddle then reviews the business.","route":"guided","gate":"human_identity","human_only":true,"gate_label":"You prove your identity","depends_on":["live_signup"],"optional":false,"url":null,"lead_time":{"official":{"text":"Business review typically takes about 10 minutes but may take longer for more complex businesses.","source_url":"https://developer.paddle.com/build/set-up-checklist/","source_title":"Setup checklist"},"reported":null,"typical_minutes":null},"preflight":[],"captures":null},{"id":"live_credentials","title":"Recreate catalog and credentials in live","summary":"Recreate products and prices, a live API key, a live client-side token, and webhook destinations in the live account. Switch base URL from sandbox-api.paddle.com to api.paddle.com.","route":"copilot","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":["live_account_setup","domain_review"],"optional":false,"url":"https://vendors.paddle.com","lead_time":null,"preflight":[],"captures":"PADDLE_API_KEY"},{"id":"live_client_token","title":"Create a live client-side token","summary":"Create the live client-side token (starts live_) for Paddle.js.","route":"copilot","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":["live_account_setup"],"optional":false,"url":"https://vendors.paddle.com","lead_time":null,"preflight":[],"captures":"NEXT_PUBLIC_PADDLE_CLIENT_TOKEN"},{"id":"webhook_destination","title":"Create a notification destination","summary":"Add a webhook destination; copy its endpoint secret key and verify the Paddle-Signature header against the raw body. Sandbox and live destinations have separate secrets.","route":"copilot","gate":"human_submit","human_only":true,"gate_label":"You press submit","depends_on":["live_account_setup"],"optional":false,"url":"https://vendors.paddle.com","lead_time":null,"preflight":[],"captures":"PADDLE_WEBHOOK_SECRET"},{"id":"default_payment_link","title":"Set the default payment link","summary":"Set the default payment link (Checkout > Checkout configuration) to a page with Paddle.js on an approved domain, not localhost; otherwise checkout fails with \"Something went wrong\".","route":"guided","gate":"none","human_only":false,"gate_label":null,"depends_on":["domain_review"],"optional":false,"url":null,"lead_time":null,"preflight":[],"captures":null}],"gates":[{"step":"sandbox_signup","gate":"human_submit","label":"You press submit"},{"step":"sandbox_api_key","gate":"human_submit","label":"You press submit"},{"step":"sandbox_client_token","gate":"human_submit","label":"You press submit"},{"step":"live_signup","gate":"human_submit","label":"You press submit"},{"step":"domain_review","gate":"third_party_review","label":"The provider reviews it"},{"step":"live_account_setup","gate":"human_identity","label":"You prove your identity"},{"step":"live_credentials","gate":"human_submit","label":"You press submit"},{"step":"live_client_token","gate":"human_submit","label":"You press submit"},{"step":"webhook_destination","gate":"human_submit","label":"You press submit"}],"lead_times":[{"step":"domain_review","what":"Submit the website domain for approval","official":{"text":"Most submissions are approved automatically; manual reviews are typically completed within an estimated 5-7 business days.","source_url":"https://www.paddle.com/help/start/account-verification/what-is-domain-verification","source_title":"Domain Review (Paddle Help Center)"},"reported":null},{"step":"live_account_setup","what":"Complete account setup and business verification","official":{"text":"Business review typically takes about 10 minutes but may take longer for more complex businesses.","source_url":"https://developer.paddle.com/build/set-up-checklist/","source_title":"Setup checklist"},"reported":null}],"outputs":[{"name":"PADDLE_API_KEY_SANDBOX","description":"Sandbox server-side API key.","secret":true,"example_format":"pdl_sdbx_apikey_…","environments":["development","test"]},{"name":"PADDLE_API_KEY","description":"Live server-side API key (backend only).","secret":true,"example_format":"pdl_live_apikey_…","environments":["production"]},{"name":"NEXT_PUBLIC_PADDLE_CLIENT_TOKEN_SANDBOX","description":"Sandbox client-side token for Paddle.js (not secret).","secret":false,"example_format":"test_…","environments":["development","test"]},{"name":"NEXT_PUBLIC_PADDLE_CLIENT_TOKEN","description":"Live client-side token for Paddle.js (not secret).","secret":false,"example_format":"live_…","environments":["production"]},{"name":"PADDLE_WEBHOOK_SECRET","description":"Endpoint secret key of a notification destination, used to verify Paddle-Signature.","secret":true,"example_format":"opaque secret string (shape only)","environments":null}],"renewals":[{"what":"Paddle API keys","every":"90 days by default (up to 1 year, chosen at creation)","every_days":90,"source_url":"https://developer.paddle.com/api-reference/about/authentication"}],"estimated_minutes":null,"guide_url":"https://verapli.com/guides/paddle/billing-api"}