Paddle

For anyone connecting Paddle to Zellify as the merchant of record for funnel payments. You'll have a live Paddle connection accepting payments with tax handled by Paddle and correct metadata. You need a Paddle account, the funnel domain approved in Paddle, and admin access to Zellify.

What this integration does#

Zellify connects to Paddle via API key. Paddle acts as the merchant of record: it invoices the customer, collects tax in every jurisdiction, and pays you net-of-fees. On the paywall Zellify creates a Paddle Customer and a Paddle Transaction, then renders the Paddle checkout form (overlay or inline) inside the funnel. Customers are created before payment completes — Paddle returns a customer id as soon as the transaction is created, so attribution and analytics can track the session even if the visitor abandons.

Zellify attaches the metadata contract under custom_data (Paddle's equivalent of Stripe's metadata) on Customers, Transactions, and Subscriptions.

Connect Paddle#

1. Open Dashboard → Settings → Payments at dash.zellify.app/settings?tab=payments.
2. Locate Paddle. Live and Sandbox connect independently.
3. Click Connect next to the environment you want to wire up.
4. Paste your Paddle API key.
5. Click Connect. Zellify provisions a client token and registers the webhook endpoints automatically.

Where to find your API key#

In Paddle, open Developer Tools → Authentication and click Generate API Key. The full URL is:

• Sandbox: https://sandbox-vendors.paddle.com/authentication-v2
• Production: https://vendors.paddle.com/authentication-v2

Configure the key with:

• Expiration: Never — Paddle expires keys by default; Zellify needs a non-expiring key so the integration doesn't quietly stop working.
• Permissions: all read and write scopes enabled. Zellify creates customers, transactions, and subscriptions, and reads them back on retry, so a partial scope set will fail in non-obvious ways.

Copy the key once it's shown — Paddle never displays it again. Match the environment of the key to the environment you're connecting in Zellify (sandbox keys won't work on the live connection and vice versa).

Approve your funnel domain in Paddle (required)#

Paddle will only render its checkout on domains that have been approved on your Paddle account. If you skip this step, your paywall will fail to load for visitors on a live account — the API call to create the transaction succeeds, but the Paddle.js overlay (or inline checkout) refuses to mount because the origin isn't on the allowlist. This is the single most common cause of "the paywall is blank" tickets.

How to approve a domain#

1. In your Paddle Dashboard, go to Paddle > Checkout > Website approval.
2. Click Request domain approval and submit the funnel domain you'll publish (the domain a customer's browser sees when the paywall renders — your custom domain if you've set one up, otherwise the Zellify-provided subdomain).
3. Wait for approval. Sandbox accounts are auto-approved instantly. Live accounts require manual review by Paddle's verification team — this typically takes a few days. Paddle confirms you own the domain and that the products being sold meet their Acceptable Use Policy.
4. Once approved, the domain appears with a check mark under Website approval.

Paddle recommends starting the live approval process early — before you finish your sandbox integration — so you're not blocked at launch.

Default payment link#

Paddle also requires a default payment link configured in Paddle > Checkout > Checkout settings > Default payment link. Set this to a URL on an approved domain (your funnel's success page works). Without it, Paddle can't construct the checkout.url that Zellify needs to open the overlay.

Tax handling (Paddle as Merchant of Record)#

Paddle collects and remits tax in every jurisdiction it supports. You don't need to register for VAT or sales tax per region. Paddle's fees are higher than Stripe's to cover this. If tax handling is the reason to pick Paddle, confirm your pricing reflects the higher take rate.

Apple Pay and Google Pay#

Apple Pay works on Paddle without extra setup, but the experience differs depending on whether you've also done Apple Pay domain verification in Paddle (a separate flow from website approval).

• Without Apple Pay domain verification: Paddle opens an unobtrusive popup from a paddle.com domain to launch the Apple Pay sheet. Functional but slightly off-brand.
• With Apple Pay domain verification: On iOS 17+, iPadOS 17+, and Safari 17+, the Apple Pay sheet launches directly from your domain — cleaner UX, higher conversion.

To enable the on-domain experience: Paddle Dashboard → Checkout → Checkout settings → Apple Pay verification, then add your funnel domain. This is in addition to website approval, not a replacement.

Checkout modes#

• Popup — Paddle overlay checkout.
• Inline — Paddle checkout rendered inline.

Apple Pay support depends on display mode and domain status.

Metadata#

Zellify attaches the following under custom_data (Paddle's equivalent of metadata):

fbp and fbc are the Meta browser and click identifiers, attached when present.

See Checkout metadata for the full contract.

Payment types#

• One-time payments
• Subscriptions
• Subscription plan changes

Upsells are not supported. See Upsell.

Free trials#

Configure trial length on the Zellify product. Paddle invoices for the first real payment at trial end.

Webhooks#

Zellify does not send payment webhooks. Paddle does. See Payment events for the Paddle event matrix.

Products and pricing#

Create products in Zellify. Zellify provisions the Paddle Product and Price. Attach to paywalls in the funnel builder.

Test and verify#

1. Switch Paddle to sandbox mode.
2. Create a test funnel.
3. Complete a test payment with Paddle's test cards.
4. Confirm in Paddle Dashboard → Transactions.
5. Confirm custom_data.app_user_id on the Transaction.

Going live#

1. Confirm your live funnel domain is approved under Paddle → Checkout → Website approval (start this days before launch — manual review takes time).
2. Confirm a default payment link is set under Paddle → Checkout → Checkout settings.
3. Switch Paddle to live in Zellify and paste the live API key.
4. (Optional) Add the same domain under Apple Pay verification for the on-domain Apple Pay sheet.
5. Run one real purchase end to end.

Troubleshooting#

Related#