Panel/docs/modules/website_billing_rebuild.md

Gameservers.World Website Billing Rebuild

Scope

The current production website remains in Panel/modules/website/. The extracted backup-website/ tree is reference-only and must not be included at runtime or copied wholesale into production.

This rebuild restores the standalone sales-site responsibilities inside the current website module:

• customer login, registration, logout, and password reset
• account, orders, invoices, and server-order review pages
• public catalog, order configuration, anonymous cart, checkout, and PayPal capture/webhook handlers
• website staff pages for services, coupons, invoices, orders, payments, PayPal settings, migrations, and provisioning queue review
• idempotent database setup for billing support tables

The GSP Panel remains responsible for operational game-server administration and final server provisioning.

Documentation and Reference Audit

Reviewed current documentation under docs/, Panel/docs/, Panel/modules/website/, and pricing/, plus backup documentation including invoice, payment, coupon, migration, testing, and status notes.

Reviewed current website implementation under Panel/modules/website/ and backup reference files including:

• login.php, logout.php, register.php, forgot_password.php, reset_password.php
• serverlist.php, order.php, add_to_cart.php, cart.php
• payment_success.php, payment_cancel.php, api/create_order.php, api/capture_order.php, webhook.php
• admin.php, adminserverlist.php, admin_config.php, admin_coupons.php, admin_invoices.php, admin_payments.php
• create_servers.php, cron-shop.php

Backup Behaviors Recreated

• Shared Panel-user authentication for the website, using the same user ID and password hash.
• Separate website and Panel sessions.
• Customer registration and password-reset pages.
• Public game-server catalog and order.php?service_id=... order entry.
• Cart, checkout, invoices, payments, and order records.
• Staff catalog, coupon, invoice, payment, PayPal, and provisioning views.

Backup Behaviors Improved

• Login now verifies the Panel password hash before creating a website session.
• The cart can be used anonymously until checkout.
• Checkout creates invoices only after the customer is authenticated.
• PayPal credentials are read from environment variables or website settings, never hardcoded in production source.
• PayPal payment state is verified server-side.
• Webhook events are deduplicated.
• CSRF tokens protect state-changing website and staff forms.
• Staff pages enforce server-side authorization.
• The backup folder is denied by .htaccess.

Backup Behaviors Rejected

• No fabricated website sessions from a submitted username.
• No production display_errors=1.
• No hardcoded PayPal client ID, client secret, or webhook ID.
• No browser-editable arbitrary PHP configuration file.
• No public inclusion of files from backup-website/.
• No provisioning before payment/approval.
• No SSO for this phase.

Credential Rotation

The backup contains historical credentials and must be treated as compromised. Rotate any credentials that were ever used from these files:

• backup-website/cart.php
• backup-website/api/create_order.php
• backup-website/api/capture_order.php
• backup-website/webhook.php
• backup-website/includes/config.inc.php
• backup-website/includes/config.inc.php.orig

Do not copy credential values from those files into documentation, commits, tickets, or chat.

Authentication

The Panel users table is the identity source. The website stores only its own PHP session state:

• website_user_id
• website_users_login
• website_users_role
• login timestamps

The website and Panel are on different parent domains, so they intentionally use separate cookies and sessions. Customers can use the same username and password on both sites, but logging into one site does not automatically log into the other.

Password verification currently matches the Panel-compatible MD5 hash used by the deployed Panel user table. Do not migrate hashes unless the Panel login system is upgraded at the same time and compatibility is tested.

Ordering Flow

1. Visitor browses serverlist.php.
2. Visitor opens order.php?service_id=<id>.
3. order.php validates the enabled service server-side.
4. Visitor chooses slots, location, duration, and optional server name.
5. The item is added to a session cart.
6. Checkout requires login or registration.
7. After login/registration, the same cart remains in the website session.
8. Checkout creates a due invoice and pending-payment order rows.
9. PayPal order creation and capture are performed server-side.
10. Verified payment marks the invoice paid and orders ready for provisioning.

Prices, slot limits, service status, and locations are revalidated on the server. Browser-submitted prices are ignored.

Database Prefix and Migrations

The website reads the current Panel database settings and table prefix from Panel/billing configuration files. Empty prefixes are supported.

Run billing setup from the staff page:

Panel/modules/website/staff_migrations.php

The migration runner creates missing tables idempotently:

• billing_invoices
• billing_orders
• billing_payments
• billing_coupons
• website_settings
• password_reset_tokens
• payment_webhook_events
• provisioning_attempts

It also adds missing catalog columns to billing_services when that table already exists:

• description
• img_url
• price_monthly
• slot_min_qty
• slot_max_qty
• enabled
• remote_server_id

Take a database backup before running migrations in production.

PayPal

Preferred production configuration uses environment variables:

• GSP_WEBSITE_PAYPAL_CLIENT_ID
• GSP_WEBSITE_PAYPAL_CLIENT_SECRET
• GSP_WEBSITE_PAYPAL_WEBHOOK_ID

The staff PayPal page can store non-environment fallback values in website_settings. Client secrets are masked and only replaced when a new value is entered.

Payment handlers:

• api/create_order.php
• api/capture_order.php
• webhook.php

Browser callbacks alone do not mark an invoice paid. Capture is verified through PayPal server-side, and webhooks are verified with PayPal before processing.

Staff Pages

Website staff pages are separate from Panel administration:

• staff.php
• staff_services.php
• staff_locations.php
• staff_coupons.php
• staff_orders.php
• staff_invoices.php
• staff_payments.php
• staff_paypal.php
• staff_settings.php
• staff_provisioning.php
• staff_migrations.php

Access is currently limited to Panel users with users_role = admin. Future role expansion can add granular permissions such as catalog.manage, orders.manage, payments.manage, and provisioning.manage.

Provisioning Boundary

The website records paid orders and exposes a provisioning queue. The Panel remains the authority for:

• creating game homes
• assigning homes to shared user_id
• selecting agents and locations
• installing server files
• operational server management

Provisioning integration must remain idempotent: paid orders should be claimed before processing, record home_id on success, and store failure details for safe retry.

Customer Pages

Customer-facing account pages:

• account.php
• orders.php
• invoices.php
• my_servers.php

my_servers.php shows website order records and links customers to the GSP control panel for operational server management.

Deployment Notes

• Serve the production website from Panel/modules/website/.
• Keep backup-website/ out of the web root where possible. The repository copy includes .htaccess deny rules as a secondary guard.
• Configure HTTPS before enabling checkout.
• Configure PayPal environment variables or staff settings.
• Run the billing migration page as an authorized staff user.
• Test sandbox PayPal before live mode.

Rollback

1. Revert changed website files.
2. Restore the database backup taken before migrations if schema rollback is required.
3. Disable PayPal in staff_paypal.php or remove the environment variables.
4. Keep backup-website/ protected; do not make it public as a rollback mechanism.

Manual Test Checklist

• Customer registration, login, invalid login, logout, forgot password, reset password.
• Catalog list, valid service_id, invalid service_id, disabled service.
• Anonymous configure, add to cart, update/remove cart item.
• Checkout prompt while logged out, login/register return to cart.
• Invoice creation, PayPal sandbox order, capture verification, webhook verification, duplicate webhook.
• Staff dashboard access as admin and denial as non-admin.
• Staff service, coupon, invoice, payment, PayPal, and provisioning pages.
• Paid order appears in provisioning queue.
• Customer orders, invoices, and My Servers pages show only the authenticated user's records.
• No hardcoded credentials or raw PHP errors are displayed.