How to Set Up Stripe for XFile Ultra

Stripe takes card payments through Stripe’s hosted Checkout. Members pay on Stripe; your site learns about a successful payment from a webhook (checkout.session.completed).

Stripe is built into XFile Ultra — no premium plugin required.

Where to find it

Admin → Settings → Payment → Stripe

1. Turn Enable Stripe checkout on

2. Paste Publishable key, Secret key, and Webhook signing secret

3. Register the shown Webhook endpoint in Stripe

4. Use Sandbox mode with test keys first

5. Save settings

6. Buy a cheap plan on /premium in a private window

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 Stripe
Enable Stripe checkout	`stripe_checkout_enabled`	Main on/off
Enable Stripe for reseller	`stripe_checkout_reseller_enabled`	Reseller top-up only
Publishable key	`stripe_publishable_key`	`pk_test_…` or `pk_live_…`
Secret key	`stripe_secret_key`	`sk_test_…` or `sk_live_…`
Webhook signing secret	`stripe_webhook_secret`	`whsec_…`
Sandbox mode	`stripe_sandbox`	Use test keys + Test-mode webhook

Optional: Checkout logo (shown on checkout).

Env overrides (when set, they win over DB): NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET.

Webhook URL:

https://YOUR-DOMAIN/api/webhooks/stripe

Event to subscribe: checkout.session.completed

Step 1 — Get API keys

1. Open the Stripe Dashboard

2. Toggle Test mode on (top) while learning

3. Go to Developers → API keys

4. Copy Publishable key (pk_test_…) and Secret key (sk_test_…)

For live later: turn Test mode off and copy pk_live_ / sk_live_ keys.

Official: Stripe API keys · Checkout

Step 2 — Create the webhook

Required event (must subscribe): checkout.session.completed

Without that event, Stripe can charge the card and XFile Ultra will not grant Premium / balance.

1. Stripe Dashboard → Developers → Webhooks

2. Stay in Test mode while Sandbox is on in XFile Ultra

3. Add endpoint

4. Endpoint URL = the admin Webhook endpoint (…/api/webhooks/stripe)

5. Under events / permissions, select only what you need — at minimum checkout.session.completed (required)

6. Add endpoint

7. Open the endpoint → Reveal signing secret (whsec_…) and copy it

When you go live, create a second webhook in Live mode (or use the Live toggle) with the same URL and the same required event.

Step 3 — Paste into XFile Ultra

1. Admin → Settings → Payment → Stripe

2. Paste publishable key, secret key, webhook signing secret

3. Turn Sandbox mode on (with test keys)

4. Turn Enable Stripe checkout on

5. Save settings

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)

Step 4 — Test

1. Ensure Currency and at least one plan under Plan & pricing

2. Private window → /premium → pay with a Stripe test card (example 4242 4242 4242 4242)

3. Confirm:

- Stripe Dashboard → Payments shows succeeded

- Admin → Payment transactions shows completed

- The member received Premium / balance

Common problems

Paid in Stripe, no Premium on the site

Webhook missing, wrong whsec_, or Test webhook while Sandbox is off (or the reverse). Check Developers → Webhooks → delivery attempts.

Keys rejected / auth errors

Test keys with Sandbox off, or live keys with Sandbox on. Match them.

Secret blank after save

Normal. Leave empty to keep the stored secret.