From 81894a5d230f1e4bf94b338b5374b47be2e23e63 Mon Sep 17 00:00:00 2001
From: Ryan Moon <moonryan2009@gmail.com>
Date: Fri, 27 Mar 2026 17:45:00 -0500
Subject: [PATCH] Update planning docs for processor-agnostic payment linking

Replace stripe_customer_id on account with account_processor_link
table. Update account_payment_method to use processor enum +
processor_payment_method_id instead of Stripe-specific fields.
Supports multiple simultaneous processors for migration scenarios.
---
 planning/02_Domain_Accounts_Customers.md | 77 ++++++++++++++++++++----
 planning/08_Domain_Payments_Billing.md   | 16 ++---
 2 files changed, 75 insertions(+), 18 deletions(-)

diff --git a/planning/02_Domain_Accounts_Customers.md b/planning/02_Domain_Accounts_Customers.md
index 2542f12..7f9396e 100644
--- a/planning/02_Domain_Accounts_Customers.md
+++ b/planning/02_Domain_Accounts_Customers.md
@@ -94,11 +94,6 @@ jsonb
 
 Street, city, state, zip
 
-stripe_customer_id
-
-varchar
-
-Stripe customer reference
 
 billing_mode
 
@@ -226,9 +221,9 @@ timestamptz
 
 
 
-## 3.3 account_payment_method
+## 3.3 account_processor_link
 
-Tracks payment methods on file. The actual card data lives in Stripe — this table only stores references.
+Links an account to a payment processor's customer record. This is processor-agnostic — supports Stripe, Global Payments, or any future processor. Replaces the previous `stripe_customer_id` column that was directly on the account table.
 
 Column
 
@@ -248,17 +243,77 @@ uuid FK
 
 
 
+company_id
+
+uuid FK
+
+Tenant scoping
+
 processor
 
 enum
 
-stripe | legacy
+stripe | global_payments
 
-stripe_payment_method_id
+processor_customer_id
 
 varchar
 
-pm_xxx reference
+The processor's customer ID (e.g. cus_xxx for Stripe, GP customer token for Global Payments)
+
+is_active
+
+boolean
+
+Allows deactivating without deleting
+
+created_at
+
+timestamptz
+
+
+
+An account may have links to multiple processors simultaneously — this is expected during migration from one processor to another (e.g. AIM legacy → Stripe transition).
+
+## 3.4 account_payment_method
+
+Tracks payment methods on file. Card data lives in the processor — this table only stores references for display and selection.
+
+Column
+
+Type
+
+Notes
+
+id
+
+uuid PK
+
+
+
+account_id
+
+uuid FK
+
+
+
+company_id
+
+uuid FK
+
+Tenant scoping
+
+processor
+
+enum
+
+stripe | global_payments
+
+processor_payment_method_id
+
+varchar
+
+Processor's payment method reference (pm_xxx for Stripe, token for GP)
 
 card_brand
 
@@ -294,7 +349,7 @@ requires_update
 
 boolean
 
-True if still on legacy processor
+True if migrated from legacy processor and needs re-entry
 
 created_at
 
diff --git a/planning/08_Domain_Payments_Billing.md b/planning/08_Domain_Payments_Billing.md
index dfed667..e724a84 100644
--- a/planning/08_Domain_Payments_Billing.md
+++ b/planning/08_Domain_Payments_Billing.md
@@ -10,25 +10,27 @@ The Payments domain describes how the application integrates with Stripe for all
 
 
 
-# 2. Stripe Entity Model
+# 2. Processor Entity Model
 
-Stripe Entity
+Payment processor customer and payment method references are stored in processor-agnostic tables, not directly on the account. This supports running multiple processors simultaneously (e.g. during migration) and adding new processors without schema changes.
+
+Processor Concept
 
 Maps To
 
 Notes
 
-Customer
+Customer (Stripe cus_xxx, GP customer token)
 
-account
+account_processor_link
 
-One Stripe customer per billing account
+One link per processor per account — multiple links allowed during migration
 
-PaymentMethod
+PaymentMethod (Stripe pm_xxx, GP payment token)
 
 account_payment_method
 
-pm_xxx stored as reference only
+Processor-agnostic — `processor` enum + `processor_payment_method_id`
 
 Subscription