From 81217722334a07befa5d0332008692830499d955 Mon Sep 17 00:00:00 2001
From: Russell Ballestrini <russell@unturf.com>
Date: Mon, 22 Dec 2025 14:21:24 -0500
Subject: [PATCH] Rename and simplify PayPal docs

---
 CHANGELOG.rst          |  2 +-
 docs/CHANGES_PAYPAL.md | 59 ------------------------------------------
 docs/PAYPAL.md         | 54 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 55 insertions(+), 60 deletions(-)
 delete mode 100644 docs/CHANGES_PAYPAL.md
 create mode 100644 docs/PAYPAL.md

diff --git a/CHANGELOG.rst b/CHANGELOG.rst
index f3432aa..e8a9b52 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -16,7 +16,7 @@ PayPal Integration
 * Checkout page supports PayPal payment option when enabled
 * Added PayPal saved payment methods (vault) support
 * Added ``/billing/disconnect-paypal`` route for users to manage saved PayPal
-* See ``docs/CHANGES_PAYPAL.md`` for implementation details
+* See ``docs/PAYPAL.md`` for details
 
 CSS Grid Lanes
 ~~~~~~~~~~~~~~
diff --git a/docs/CHANGES_PAYPAL.md b/docs/CHANGES_PAYPAL.md
deleted file mode 100644
index abb679b..0000000
--- a/docs/CHANGES_PAYPAL.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# PayPal Integration
-
-**Released:** December 22, 2025 at 2:30 PM
-
-Adds PayPal as a payment processor alongside Stripe and crypto (XMR/DOGE).
-
-## Files Added
-
-### Models
-- `make_post_sell/models/paypal_user_shop.py` - Tracks PayPal payer IDs per user/shop (for saved payment methods)
-
-### Views
-- `make_post_sell/views/paypal.py` - Order creation and checkout capture
-- `make_post_sell/views/paypal_webhooks.py` - Webhook handler for payment events
-
-### Migration
-- `make_post_sell/scripts/alembic/versions/418933067d81_add_paypal_support.py`
-  - Adds `paypal_client_id`, `paypal_secret`, `paypal_enabled` to mps_shop
-  - Adds `paypal_order_id`, `paypal_capture_id` to mps_invoice
-  - New table (mps_paypal_user_shop) is auto-created
-
-## Files Modified
-
-- `make_post_sell/models/__init__.py` - Import PayPalUserShop
-- `make_post_sell/models/meta.py` - Register PayPalUserShop in CLASS_TO_TABLE
-- `make_post_sell/models/shop.py` - PayPal columns, `is_paypal_ready`, `paypal_user_shop()`
-- `make_post_sell/models/invoice.py` - PayPal columns, updated `payment_method` property
-- `make_post_sell/routes.py` - PayPal routes
-- `make_post_sell/request_methods.py` - `request.paypal_enabled`
-- `make_post_sell/views/cart.py` - Pass PayPal context to checkout template
-- `make_post_sell/templates/cart_checkout.j2` - PayPal button
-- `make_post_sell/templates/shop_settings.j2` - PayPal settings form
-- `make_post_sell/static/css/common.css` - PayPal input styles
-- `development.ini` - PayPal config settings
-
-## Configuration
-
-In `development.ini`:
-```ini
-app.payments.paypal.enabled = True
-app.paypal.sandbox_mode = True
-```
-
-Or via environment:
-```bash
-export MPS_PAYMENTS_PAYPAL_ENABLED=True
-export MPS_PAYPAL_SANDBOX_MODE=True
-```
-
-## Shop Setup
-
-1. Get credentials from https://developer.paypal.com/dashboard/
-2. Go to Shop Settings → PayPal Settings
-3. Enter Client ID and Secret
-4. Save
-
-## Dependencies
-
-- `paypalrestsdk` (added to requirements)
diff --git a/docs/PAYPAL.md b/docs/PAYPAL.md
new file mode 100644
index 0000000..2c373fa
--- /dev/null
+++ b/docs/PAYPAL.md
@@ -0,0 +1,54 @@
+# PayPal Payments
+
+PayPal is available as a payment method alongside Stripe and crypto (XMR/DOGE).
+
+## Shop Setup
+
+1. Go to https://developer.paypal.com/dashboard/
+2. Create an app (sandbox for testing, live for production)
+3. Copy Client ID and Secret
+4. In Shop Settings → PayPal Settings, enter credentials and save
+
+## Configuration
+
+Global settings in `development.ini`:
+
+```ini
+app.payments.paypal.enabled = True
+app.paypal.sandbox_mode = True
+```
+
+Or environment variables:
+
+```bash
+export MPS_PAYMENTS_PAYPAL_ENABLED=True
+export MPS_PAYPAL_SANDBOX_MODE=True
+```
+
+## How It Works
+
+- Each shop configures their own PayPal credentials
+- PayPal button appears at checkout when enabled
+- Payment info stored on Invoice (`paypal_order_id`, `paypal_capture_id`)
+- `Invoice.payment_method` returns "paypal" for PayPal payments
+- Saved payment methods stored in `PayPalUserShop`
+
+## Routes
+
+- `POST /paypal/create-order/{cart_id}` - Creates PayPal order (called by JS SDK)
+- `POST /paypal/complete-checkout/{cart_id}` - Captures payment, creates invoice
+- `POST /webhooks/paypal` - Webhook handler for payment events
+
+## Database
+
+**mps_shop columns:**
+- `paypal_client_id` - Shop's PayPal Client ID
+- `paypal_secret` - Shop's PayPal Secret
+- `paypal_enabled` - Toggle PayPal on/off
+
+**mps_invoice columns:**
+- `paypal_order_id` - PayPal order reference
+- `paypal_capture_id` - PayPal capture reference
+
+**mps_paypal_user_shop table:**
+- Tracks saved PayPal payment methods per user/shop