# SideLedger — Online Payments & Auto Mark Paid



SideLedger can add a **Pay online** link to every invoice (Pro+) and (with Elite + cloud sign-in) automatically mark invoices **paid** when Stripe reports a successful payment via Zapier.



---



## What works by tier



| Feature | Who |

|--------|-----|

| Configure Stripe, PayPal.me, Venmo, Cash App, Zelle note, custom URL | **Pro** or **Elite** (Account → Online payments) |

| Auto-generate payment link on invoice preview / PDF / email / collections | **Pro** or **Elite** |

| Manual **Mark paid** on Collections | **Pro** or **Elite** |

| Zapier → Supabase webhook → auto mark paid on sync | **Elite** + signed in + SQL below |



Free users can create invoices but payment links are not generated or shown.



---



## 1. Configure payment providers in SideLedger



1. Activate **Pro** or **Elite**, then open **Account** → **Online payments** (`account.html#payment-settings`).

2. Enable your provider(s) and save:

   - **Stripe** — paste a [Stripe Payment Link](https://dashboard.stripe.com/payment-links) URL. Use `{invoice}` in the URL or Stripe metadata so payments can be matched.

   - **PayPal.me** — your username (link becomes `https://paypal.me/you/125.00`).

   - **Venmo / Cash App** — username or $cashtag (manual confirm only; no auto webhook).

   - **Zelle** — display note on invoice (manual confirm).

   - **Custom URL** — any HTTPS template with `{amount}`, `{invoice}`, `{client}`, `{currency}`.

3. Leave **Payment link** blank on an invoice to auto-fill from these settings.



Each saved invoice stores `paymentReference` = invoice number (e.g. `INV-001`) for webhook matching.



---



## 2. Run Supabase SQL (auto mark paid)



In Supabase **SQL Editor**, run the full script:



**`supabase/payments.sql`**



This creates:



- `payment_webhook_secrets` — your per-user webhook secret

- `invoice_payment_events` — payment records the app pulls on sync

- RPC `register_payment_webhook_secret` — client registers secret when you save settings

- RPC `record_invoice_payment_webhook` — Zapier POST target

- RPC `mark_invoice_paid_by_ref` — optional manual import while signed in



---



## 3. Enable auto mark-paid in SideLedger (Elite)



1. Activate **Elite** and sign in (Account page).

2. **Online payments** → check **Enable auto mark-paid sync** → **Save payment settings**.

3. Copy your **webhook secret** (or click **New secret** if needed).



Pro users can send payment links but must mark invoices paid manually on Collections.



---



## 4. Stripe + Zapier setup (step by step)



### A. Stripe Payment Link with invoice reference



**Option 1 — Metadata (recommended)**



1. Stripe Dashboard → **Payment Links** → create or edit a link.

2. Under **After payment** or custom fields, ensure the customer sees the invoice number, **or** use a Stripe Checkout Session via Zapier with `client_reference_id` = invoice number from SideLedger.



**Option 2 — Fixed Payment Link + manual memo**



If you use one link for all amounts, ask customers to put the invoice number (`INV-001`) in the Stripe description/memo. Map that field in Zapier (step C).



For variable amounts, prefer PayPal.me or a custom URL template with `{amount}`.



### B. Create a Zap



1. Go to [zapier.com](https://zapier.com) → **Create Zap**.

2. **Trigger:** Stripe → **New Payment** (or **Payment Intent Succeeded** / **Checkout Session Completed**).

3. Connect your Stripe account.

4. Test the trigger with a small live or test payment.



### C. Action — Webhooks by Zapier (POST)



1. **Action:** Webhooks by Zapier → **POST**.

2. **URL:**



   ```

   https://YOUR-PROJECT.supabase.co/rest/v1/rpc/record_invoice_payment_webhook

   ```



   Replace `YOUR-PROJECT` with your Supabase project ref (same as `js/config.js` → `supabaseUrl`).



3. **Headers:**



   | Key | Value |

   |-----|--------|

   | `apikey` | Your Supabase **anon/publishable** key (from Project Settings → API) |

   | `Content-Type` | `application/json` |

   | `Prefer` | `return=representation` |



4. **Data (JSON body)** — map Stripe fields to:



   ```json

   {

     "p_secret": "YOUR_WEBHOOK_SECRET_FROM_SIDELEDGER",

     "p_invoice_number": "INV-001",

     "p_amount": 125.00,

     "p_provider": "stripe"

   }

   ```



   Map `p_invoice_number` from Stripe metadata, `client_reference_id`, or description — **must match** the invoice number in SideLedger history exactly (e.g. `INV-001`).



5. Turn the Zap **On**.



### D. Verify



1. Create an invoice in SideLedger, download PDF (saves to history with `INV-xxx`).

2. Pay via Stripe with that invoice number in metadata/reference.

3. Open SideLedger (signed in, **Elite**) → Account → **Check for payments now**, or reload the app.

4. Toast: **Payment received — marked paid: INV-xxx**. Collections and invoice history show **Paid**.



---



## 5. Webhook payload reference



| Field | Required | Description |

|-------|----------|-------------|

| `p_secret` | Yes | From Account → Online payments |

| `p_invoice_number` | Yes | Must match SideLedger invoice number |

| `p_amount` | No | Stored for records; not used to validate amount yet |

| `p_provider` | No | Default `stripe` |



Make.com uses the same POST URL and JSON body.



---



## 6. Limitations (v1)



- **No native Stripe OAuth** — you paste Payment Link URLs or use Zapier; SideLedger does not call Stripe API from the browser.

- **Amount matching** — webhook does not verify amount equals invoice total; match is by invoice number only.

- **Venmo / Cash App / Zelle** — links only; no automatic webhook. Mark paid manually on Collections.

- **Offline users** — payment events require sign-in + sync; unsigned users keep manual mark paid.

- **Duplicate events** — repeated webhooks for the same invoice create multiple rows; already-paid invoices are skipped locally.

- **Edge Function** — v1 uses Supabase RPC + anon key; keep webhook secret private in Zapier only.



---



## 7. Files in this repo



| File | Purpose |

|------|---------|

| `js/payments.js` | Provider settings, URL templates, link generation |

| `js/payment-sync.js` | Pull events, mark invoices paid, toasts |

| `js/payment-settings.js` | Account page UI |

| `supabase/payments.sql` | Database tables + RPCs |

| `account.html#payment-settings` | Settings UI |



See also **AUTH-SETUP.md** for Supabase project setup and **LICENSE-KEYS.md** for Pro/Elite activation.