SPEC 010 — Payments

Field	Value
Status	DRAFT
Priority	P1 — Core Product
Backend	`equa-server/modules/billing/`
API	`equa-server/modules/api/src/endpoints/billing-endpoints.ts`
Frontend	`equa-web/src/modules/payments/`, `equa-web/src/modules/subscriptions/`

1. Feature Purpose

Payments handles the commercial side of the Equa platform: subscription plan selection, checkout, payment profile management (credit cards and bank accounts), billing history, promotional discounts, and EquaCash (in-platform credits). The backend integrates with Chargify (not Stripe) for all payment processing, subscription lifecycle, and billing.

2. Current State (Verified)

2.1 Backend

Component	Path
Billing module root	`equa-server/modules/billing/src/`
Chargify network layer	`equa-server/modules/billing/src/network.ts`
Billing types	`equa-server/modules/billing/src/types.ts`
Billing requests	`equa-server/modules/billing/src/requests.ts`
Billing responses	`equa-server/modules/billing/src/responses.ts`
Billing reading	`equa-server/modules/billing/src/reading.ts`
Billing writing	`equa-server/modules/billing/src/writing.ts`
Billing utility	`equa-server/modules/billing/src/utility.ts`
API endpoints	`equa-server/modules/api/src/endpoints/billing-endpoints.ts`

2.2 Frontend

Component	Path
Payments module	`equa-web/src/modules/payments/`
Subscriptions module	`equa-web/src/modules/subscriptions/`
Payment service types	`equa-web/src/logic/services/payments.ts`
Payment service URLs	`equa-web/src/service/services/payments/urls.ts`
Payment service reading	`equa-web/src/service/services/payments/reading.ts`
Payment service writing	`equa-web/src/service/services/payments/writing.ts`
Billing service	`equa-web/src/service/services/billing/`
Profile card pages	`equa-web/src/modules/profile/pages/add-card-page.tsx`, `edit-card-page.tsx`, `view-card-page.tsx`

3. Data Model

3.1 Chargify Integration (External)

Payments does not store subscription or payment data in the Equa database. All payment state lives in Chargify. The backend acts as a proxy/adapter between the Equa API and Chargify’s REST API. ChargifyConfig (billing/types.ts lines 2–5):

Field	Type	Description
apiKey	string	Chargify API key
subdomain	string	Chargify account subdomain

ChargifySubscription (billing/types.ts lines 30–38):

Field	Type	Description
id	number	Chargify subscription ID
product	ChargifyProduct	Product reference (id)
activated_at	string	Activation timestamp
current_period_ends_at	string	nullable, current period end
expires_at	string	Expiration timestamp
bank_account	any	Bank account details
credit_card	ChargifyCreditCard	nullable, card details

ChargifyCreditCard (billing/types.ts lines 17–24):

Field	Type
id	number
billing_address	string
billing_city	string
billing_state	string
billing_zip	string
billing_country	string

3.2 EquaCash

EquaCash is an in-platform credits/balance system that offsets subscription costs during checkout. When total_in_cents is covered by EquaCash, no external payment is required.

3.3 UserCoupons (Database)

Column	Type	Description
user	uuid	FK → Users
coupon	varchar	Coupon/promo code

Source: schema.ts (UserCoupons entity)

4. API Endpoints

Product and Pricing

Method	Path	Auth Guard	Description
GET	`/billing/product`	None	List available products/plans
GET	`/billing/member/pricing`	None	Get per-member price points

Subscriptions

Method	Path	Auth Guard	Description
GET	`/organization/:organization/subscription`	canEditOrganizationBilling	List org subscriptions
GET	`/organization/:organization/features`	canViewOrganization	List org features/entitlements
POST	`/organization/:organization/subscription`	canEditOrganizationBilling	Create new subscription
POST	`/organization/:organization/subscription/preview`	canEditOrganizationBilling	Preview purchase (price calculation without committing)
DELETE	`/organization/:organization/subscription/:subscription`	canEditOrganizationBilling	Cancel subscription

Payment Profiles

Payment profiles are scoped to entities (not organizations), allowing the same entity to manage payment methods across multiple organizations.

Method	Path	Auth Guard	Description
POST	`/entity/:entity/payment/profile`	canEditEntityBilling	Create payment profile
GET	`/entity/:entity/payment/profile`	canEditEntityBilling	List payment profiles
PUT	`/entity/:entity/payment/profile/:profile`	canEditEntityBilling	Update payment profile
PUT	`/entity/:entity/payment/profile/:profile/default`	canEditEntityBilling	Set as default profile
DELETE	`/entity/:entity/payment/profile/:profile`	canEditEntityBilling	Delete payment profile

Method	Path	Auth Guard	Description
GET	`/organization/:organization/billing/transaction`	canEditOrganizationBilling	List billing transactions
POST	`/promo/validate`	None	Validate promotional code
POST	`/subscriptions/:subscription/adjustments`	None	Create billing adjustment

Source: billing-endpoints.ts lines 34–161

5. Frontend Components

Pages

Component	File	Purpose
BillingPage	`payments/pages/billing-page.tsx`	Current subscription, payment profiles, billing history
SelectYourPlanPage	`payments/pages/select-your-plan-page.tsx`	Plan selection with feature comparison
CheckoutPage	`payments/pages/check-out-page.tsx`	Payment execution with profile selection, EquaCash, promo
NewPaymentProfilePage	`payments/pages/new-payment-profile.tsx`	Add credit card or bank account
EditPaymentProfilePage	`payments/pages/edit-payment-profile.tsx`	Update payment method

Components

Component	File	Purpose
PaymentProfiles	`payments/components/payment-profiles.tsx`	Payment method selector (radio list)
CartSummary	`payments/components/cart-summary.tsx`	Order total with line items (desktop sidebar)
CartSummaryModal	`payments/components/cart-summary-modal.tsx`	Order total (mobile modal)
FeaturesTable	`payments/components/features-and-additional-services.tsx`	Plan feature comparison matrix
PaymentHistory	`subscriptions/components/payment-history.tsx`	Transaction history table

Routes

Route	Component
`/organization/:organization/billing`	BillingPage
`/organization/:organization/checkout`	CheckoutPage
`/organization/:organization/select-your-plan`	SelectYourPlanPage
`/organization/:organization/payment-profile/new`	NewPaymentProfilePage
`/organization/:organization/payment-profile/:profile/edit`	EditPaymentProfilePage

Checkout Flow

The checkout page (check-out-page.tsx) follows a multi-step process:

Select payment profile — User picks from existing profiles or adds new one
Apply EquaCash — Platform credits offset the total
Enter promo code — Optional coupon discount
Preview purchase — Calls /subscription/preview to show final price
Submit — Creates subscription via POST /organization/:organization/subscription
Modals — Processing spinner, success confirmation, or error notification

State:

selectedProfile: number — Currently selected payment profile ID
couponValue: number — Applied coupon discount
remove: boolean — Whether removing a profile

Checkout enums (helpers/enum.ts):

enum Steps { checkout = 0, confirm = 1, thanks = 2 }
enum PaymentSteps { selectPlan = 0, checkout = 1 }

Submit validation: Disabled when total_in_cents !== 0 and no profile is selected, or when total is fully covered by EquaCash.

Request/Response Types

interface NewAddressRequest {
  street1: string; street2?: string; street3?: string;
  country: string; city: string; postalCode: string; province: string;
}

interface CreditCardRequest {
  firstName?: string; lastName?: string;
  fullNumber?: string; expirationMonth?: number;
  expirationYear?: number; cvv?: string;
}

interface NewPaymentProfileRequest extends OrganizationRequest, PaymentRequest {
  billingAddress: NewAddressRequest;
  creditCard?: CreditCardRequest;
}

interface NewSubscriptionRequest extends PurchaseRequest, PaymentRequest {
  billingAddress?: NewAddressRequest;
  savePaymentInfo?: boolean;
  creditCard?: CreditCardRequest;
  acceptedTerms?: boolean;
  paymentProfile?: number;  // existing profile ID
}

interface SubscriptionResponse {
  product: string | number;
  productPriceInCents: number;
  nextPriceInCents: number;
  lineItems: BillingLineItem[];
  startDate: string;
  renewDate: string;
  bankAccount?: BankAccountResponse;
  creditCard?: CreditCardResponse;
  billingAddress?: NewAddressRequest;
}

6. Business Rules and Validation

Rule	Description	Enforcement
Entity-scoped payment profiles	Payment profiles belong to entities, not organizations. An entity can have profiles used across multiple orgs.	API path: `/entity/:entity/payment/profile`
Default profile	One profile can be set as default per entity via the dedicated endpoint	Backend sets default, returns updated list
Subscription preview	Before committing, `/subscription/preview` calculates the exact charge including promo codes and EquaCash	Backend Chargify API call
EquaCash offset	If EquaCash balance covers the full amount (`total_in_cents === 0`), no payment profile is needed	Frontend skips profile selection
Promo code validation	Codes are validated against Chargify via `POST /promo/validate` before applying	Backend validates, frontend stores discount
Terms acceptance	`acceptedTerms` must be true to create a subscription	Frontend form validation
Unauthenticated endpoints	Product listing, pricing, promo validation, and adjustments require no auth	By design — public pricing info
Permission guards	Subscription management requires `canEditOrganizationBilling`; payment profiles require `canEditEntityBilling`	API endpoint guards
Billing adjustment	Adjustments are posted directly to Chargify by subscription ID	No org-level auth check (potential gap)

7. Acceptance Criteria

8. Risks and Edge Cases

Risk	Impact	Mitigation
Chargify API downtime	Users cannot create subscriptions or manage profiles	Display clear error messages; consider caching product/pricing data
Adjustment endpoint has no auth guard	Unauthorized billing adjustments	Add `canEditOrganizationBilling` guard to adjustments endpoint
Credit card data handling	PCI compliance requirements	Card data sent directly to Chargify; Equa server never stores full card numbers
EquaCash balance race condition	Two concurrent checkouts could double-spend credits	Serialize EquaCash deductions on the server
Subscription state sync	Local state may diverge from Chargify’s actual state	Always fetch fresh subscription data from Chargify on page load
Expired credit card	Renewal failure	Chargify handles dunning; surface renewal failure in billing page
Promo code abuse	Same code used multiple times	Chargify tracks usage limits per code
Entity vs organization confusion	Users may not understand why profiles are entity-scoped	UI should explain that payment methods are linked to their account, not the organization

9. Dependencies

Dependency	Type	Status
001-Authentication (user sessions)	Required before	DRAFT
002-Organization Management	Required before	DRAFT
011-Billing and Subscriptions (feature entitlements)	Integrates with	DRAFT
012-Team Members and Roles (billing permissions)	Required before	DRAFT

Platform Architecture

Compliance & Security

Feature Specifications

Developer Onboarding

Business

Reference & Templates

Payments

SPEC 010 — Payments

1. Feature Purpose

2. Current State (Verified)

2.1 Backend

2.2 Frontend

3. Data Model

3.1 Chargify Integration (External)

3.2 EquaCash

3.3 UserCoupons (Database)

4. API Endpoints

Product and Pricing

Subscriptions

Payment Profiles

5. Frontend Components

Pages

Components

Routes

Checkout Flow

Request/Response Types

6. Business Rules and Validation

7. Acceptance Criteria

8. Risks and Edge Cases

9. Dependencies

Platform Architecture

Compliance & Security

Feature Specifications

Developer Onboarding

Business

Reference & Templates

​SPEC 010 — Payments

​1. Feature Purpose

​2. Current State (Verified)

​2.1 Backend

​2.2 Frontend

​3. Data Model

​3.1 Chargify Integration (External)

​3.2 EquaCash

​3.3 UserCoupons (Database)

​4. API Endpoints

​Product and Pricing

​Subscriptions

​Payment Profiles

​Billing History and Promo

​5. Frontend Components

​Pages

​Components

​Routes

​Checkout Flow

​Request/Response Types

​6. Business Rules and Validation

​7. Acceptance Criteria

​8. Risks and Edge Cases

​9. Dependencies

SPEC 010 — Payments

1. Feature Purpose

2. Current State (Verified)

2.1 Backend

2.2 Frontend

3. Data Model

3.1 Chargify Integration (External)

3.2 EquaCash

3.3 UserCoupons (Database)

4. API Endpoints

Product and Pricing

Subscriptions

Payment Profiles

Billing History and Promo

5. Frontend Components

Pages

Components

Routes

Checkout Flow

Request/Response Types

6. Business Rules and Validation

7. Acceptance Criteria

8. Risks and Edge Cases

9. Dependencies