Viwosi Labs
Premium & PayPal

Optional Premium payments through PayPal

ServerList is free to use. This document covers the optional PayPal checkout feature an operator can offer for Premium periods on servers listed on that operator's own installation. It does not create a paid ServerList edition.

Premium packages are managed in Admin > Premium. All packages grant the existing Premium feature level. Purchasers choose a package, then one of their owned, claimed, approved, visible servers. Orders copy the package's exact amount, currency, name and duration; subsequent package changes or deletion do not change the purchase.

Configuration and Sandbox verification

  1. In your PayPal Business developer account, create/select your installation's REST app under Sandbox. Use its Client ID and Client Secret. Never use a real buyer for testing. Sandbox fulfilment adds actual Premium periods to this installation, so use a non-production installation.
  2. The application's configured APP_URL must be the correct public HTTPS origin, reachable by PayPal on port 443. Callback URLs are built from this trusted configuration, not the incoming Host header.
  3. Register https://YOUR-SERVERLIST-HOST/webhooks/paypal/sandbox on that same Sandbox app. Subscribe to CHECKOUT.ORDER.APPROVED, PAYMENT.CAPTURE.COMPLETED, PAYMENT.CAPTURE.PENDING, PAYMENT.CAPTURE.DENIED, PAYMENT.CAPTURE.REFUNDED and PAYMENT.CAPTURE.REVERSED. Save the resulting Webhook ID.
  4. In Admin > Premium > PayPal settings, enter those three values in the Sandbox section, choose Sandbox and enable purchases. All credential fields are encrypted; blank fields preserve stored values. Credentials are never populated in the form or validation's old input.
  5. Using a verified ServerList account with an eligible server, choose a package at /premium, choose the server, and continue to the order and PayPal. Sign in with a separate PayPal Sandbox personal/buyer account and approve.
  6. On return, use Confirm / check payment. The approved-order webhook can also complete the capture when the buyer does not return. Check the order's fulfilled state in Admin > Premium > Payment orders and the added Premium period. Repeat confirmation and resend the completed webhook: exactly one period must be added.
  7. Also test cancellation, delayed confirmation, an existing paused/future Premium period and a server becoming ineligible after approval. Refund/reversal events must flag the order without deleting Premium.

The PayPal webhook simulator does not support the postback verification used here. Use real Sandbox transactions and event resends from the Sandbox REST app.

Live credentials and the /webhooks/paypal/live webhook are separate. Moving to live is an operator action after Sandbox testing; this implementation does not provision credentials, accounts or webhooks. Keep previous environment credentials/webhooks available for outstanding payments. Rotating a secret for the same Client ID is supported; switching Client IDs prevents old orders from being verified until the original app credentials are restored. Disabling purchases stops new orders, while existing orders and webhooks can still complete.

Recovery and entitlement rules

The local order exists before remote creation. Create/capture retries reuse their persisted PayPal-Request-Id. If creation has an ambiguous result older than PayPal's default six-hour idempotency retention, the order is flagged for review instead of risking a second remote order. A signed webhook can recover the remote identifier after a process crash. Following a capture timeout, use the same order's check button; canonical PayPal order details are fetched before attempting another capture. Do not create another purchase just because confirmation was interrupted.

Network calls run outside database transactions. Fulfilment locks the order and server, validates the completed capture and rechecks server eligibility. It inserts the period and marks fulfilment in one transaction. Repeated callbacks cannot grant twice. New time starts after the latest reserved end date, including paused/manual periods, or now if there is no unexpired reservation. Existing periods are never shortened or overwritten. Manual assignment uses the same server lock when checking overlaps.

Payments for servers that are no longer eligible (including deleted/transferred servers) are flagged for administrator review. Restoring eligibility does not automatically release that review. Refunds, reversals and denials are recorded for review; there is no automated refund or entitlement removal. Administrators use the recorded provider order/capture identifiers to inspect PayPal and make any necessary manual Premium adjustment. Order history survives package, server and user deletion; it stores no card data or webhook payloads.

Webhook signatures are verified with PayPal's official verification API and the environment's stored Webhook ID. Durable processed-event identifiers suppress duplicates. A temporary verification/API error returns a failure response so PayPal can retry. PayPal retries are finite: administrators should investigate orders left pending or in review, and resend the real webhook or ask the purchaser to recheck the existing order after correcting configuration. There is no additional polling scheduler in this phase.

Reference: PayPal Orders v2, webhook verification and retries, idempotency.