How to Set Up BTCPay Server for XFile Ultra
BTCPay Server is self-hosted crypto checkout (Bitcoin, Lightning, and other methods you enable on the store). XFile Ultra creates invoices on your BTCPay instance and fulfills when the webhook receives InvoiceSettled.
There is no Sandbox toggle in admin — use a separate BTCPay test store / instance if you need a dry run.
Premium plugin required
BTCPay needs the BTCPay Payment premium plugin.
1. Buy BTCPay Payment on xfileultra.com
2. Refresh the license under Admin → Settings → Main → Site identity
3. Until licensed, the BTCPay section stays locked
Where to find it
Admin → Settings → Payment → BTCPay Server
1. Turn Enable BTCPay checkout on
2. Paste Server URL, Store ID, API key, and Webhook secret
3. Register the webhook on that store for InvoiceSettled
4. Enable payment methods (BTC, Lightning, …) inside BTCPay, not in this panel
5. 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 BTCPay |
|---|---|---|
| Enable | btcpay_checkout_enabled |
Main on/off |
| Enable for reseller | btcpay_checkout_reseller_enabled |
Reseller top-up |
| Server URL | btcpay_server_url |
https://btcpay.example.com (no trailing slash) |
| Store ID | btcpay_store_id |
Store → Settings → General |
| API key | btcpay_api_key |
Greenfield API key |
| Webhook secret | btcpay_webhook_secret |
Store webhook secret |
Webhook URL:
https://YOUR-DOMAIN/api/webhooks/btcpayEvent: InvoiceSettled
Return (automatic): /api/checkout/btcpay/return
Env overrides: BTCPAY_SERVER_URL, BTCPAY_STORE_ID, BTCPAY_API_KEY, BTCPAY_WEBHOOK_SECRET.
Step 1 — Server URL and Store ID
1. Open your BTCPay Server web UI
2. Copy the public base URL (https, no path, no trailing slash) into Server URL
3. Open your Store → Settings → General
4. Copy the Store ID
The BTCPay host must be reachable from your XFile Ultra VPS and from customers’ browsers.
Step 2 — Greenfield API key
1. In BTCPay, create an API key (Account / Store API keys — Greenfield)
2. Grant permission to create invoices for that store (and any related invoice read permissions your BTCPay version recommends)
3. Copy the API key into XFile Ultra
Official: BTCPay Greenfield API
Step 3 — Webhook on the store
Required event (must subscribe): InvoiceSettled
Without that event, BTCPay can settle the invoice and XFile Ultra will not grant Premium / balance.
1. BTCPay → Store → Settings → Webhooks
2. Add webhook URL = admin endpoint
3. Under event subscriptions / permissions, enable InvoiceSettled (required)
4. Copy the webhook secret into XFile Ultra
Step 4 — Enable coins in BTCPay
Under the store’s Payment methods, enable Bitcoin / Lightning / altcoins you want. XFile Ultra does not list coins in Payment settings — it uses whatever the store offers.
Step 5 — Paste into XFile Ultra and test
1. Admin → Settings → Payment → BTCPay Server
2. Fill all four fields → enable → Save
3. Pay a small invoice on /premium
4. Confirm Payment transactions + entitlement after settlement
Common problems
Connection / create invoice errors
Wrong Server URL, Store ID typo, API key missing invoice permission, or BTCPay unreachable from the VPS.
Invoice paid, site not upgraded
Webhook secret mismatch, webhook on the wrong store, or event not InvoiceSettled.
Section locked
Buy BTCPay Payment on xfileultra.com and refresh the license.