How to Set Up Paddle for XFile Ultra
Paddle is a merchant-of-record checkout (Paddle handles tax/VAT for one-time Premium / top-up payments).
Premium plugin required
Paddle needs the Paddle Payment premium plugin.
1. Buy Paddle Payment on xfileultra.com
2. In your XFile Ultra install: Admin → Settings → Main → Site identity → refresh / re-check the license
3. Until licensed, the Paddle section stays locked
Where to find it
Admin → Settings → Payment → Paddle
1. Turn Enable Paddle checkout on
2. Paste API key, Client-side token, and Webhook secret
3. In Paddle, approve your domain under Checkout → Website approval
4. In Paddle, set Default payment link to /premium/paddle (not the return URL)
5. Register the notifications webhook (transaction.completed)
6. Use Sandbox mode with sandbox credentials first
7. Save settings and test
Enable for reseller (optional): shows this gateway on reseller balance top-up checkout. Member Premium upgrade and member balance top-up use the main Enable toggle only. Reseller enable needs the Reseller System premium plugin.
Fields in XFile Ultra
| Field | Setting key | From Paddle |
|---|---|---|
| Enable Paddle checkout | paddle_checkout_enabled |
Main on/off |
| Enable Paddle for reseller | paddle_checkout_reseller_enabled |
Reseller top-up |
| API key | paddle_api_key |
pdl_…_apikey_… |
| Client-side token | paddle_client_side_token |
test_… / live_… |
| Webhook secret | paddle_webhook_secret |
Notification secret (pdl_ntfset_…) |
| Sandbox mode | paddle_sandbox |
sandbox-api vs live |
Webhook URL:
https://YOUR-DOMAIN/api/webhooks/paddleRequired notification event: transaction.completed (required). The app also accepts transaction.paid if you subscribe to it.
Important Paddle URLs:
| Purpose | URL |
|---|---|
| Default payment link (set in Paddle) | https://YOUR-DOMAIN/premium/paddle |
| Return (automatic) | https://YOUR-DOMAIN/api/checkout/paddle/return |
Do not put the return URL in Default payment link — that page must load Paddle.js.
Env overrides: PADDLE_API_KEY, PADDLE_CLIENT_SIDE_TOKEN / NEXT_PUBLIC_PADDLE_CLIENT_SIDE_TOKEN, PADDLE_WEBHOOK_SECRET.
Step 1 — Create authentication credentials
1. Open Paddle (use sandbox while learning)
2. Developer tools → Authentication
3. Create an API key (pdl_…_apikey_…)
4. Create a client-side token (test_ / live_)
5. Do not paste the client-side token into the API key field
Official: Paddle Checkout
Step 2 — Website / domain approval (required for live)
Paddle only serves checkout on approved domains. This step is required for live checkouts.
1. In the Paddle dashboard, go to Checkout → Website approval (sometimes labeled Domain approval)
2. Submit your live site domain (example: example.com)
3. If you also sell on www.example.com or another subdomain, submit each host you will open checkout from
4. Wait until the domain status is approved before expecting live Paddle.js checkout to work
Sandbox domains are typically auto-approved. Live accounts go through Paddle’s review — do not skip this step.
Help: Paddle domain / website approval
Step 3 — Notifications (webhook)
Required event (must subscribe): transaction.completed
Optional but accepted: transaction.paid.
Without transaction.completed (or transaction.paid), Paddle can take payment and XFile Ultra may not fulfill the order.
1. Paddle → Developer tools → Notifications
2. Add destination URL = admin webhook endpoint
3. Under event subscriptions / permissions, enable transaction.completed (required)
4. Copy the notification secret (pdl_ntfset_…) — not only the destination id (ntfset_…)
5. Paste into Webhook secret in XFile Ultra
Step 4 — Default payment link
1. Paddle → Checkout → Checkout settings (wording may vary slightly)
2. Set Default payment link to:
https://YOUR-DOMAIN/premium/paddleThis is required for Paddle.js hosted checkout to open correctly.
Step 5 — Paste into XFile Ultra
1. Admin → Settings → Payment → Paddle
2. Paste API key, client-side token, webhook secret
3. Sandbox on with sandbox credentials
4. Enable checkout → Save
5. Test a cheap plan on /premium
What is Sandbox / Test mode?
Sandbox (sometimes labeled Test mode) means you use the provider’s test environment — fake cards, fake buyers, no real money. Turn it on while learning. When you go live:
1. Turn Sandbox / Test mode off
2. Paste live keys (not test keys)
3. Register live webhooks (Stripe/PayPal have separate Test vs Live webhook endpoints)
Common problems
Checkout never opens / domain not approved
Domain missing under Checkout → Website approval, still pending review, or you submitted apex but checkout runs on www (or the reverse). Approve every host you use.
Checkout never opens (link wrong)
Default payment link is wrong. It must be /premium/paddle, not the return URL.
Webhook secret rejected
You pasted the destination id instead of the pdl_ntfset_ secret.
Section locked
Buy Paddle Payment on xfileultra.com and refresh the license in Site identity.