Payment System

What It Does

Full payment lifecycle management. Tracks from billing through collection with automated reminders. PayPal webhooks handle online payments; manual entry covers clinic payments. The system auto-calculates the 10% commission owed on Oshun revenue.

• Receives and verifies PayPal webhook events for online payments
• Manages a 6-state payment state machine from awaiting through complete
• Sends automated reminders at defined escalation intervals (day 3, 7, 14, 30)
• Tracks commissions against the Oshun deal: $500/mo base + 10% commission on revenue
• Logs all payment events and accounting sync actions for reconciliation

External Service Details

External service: PayPal (sandbox + live modes)

Oshun deal: $500/mo base + 10% commission on all client revenue.

Required environment variables:

• PAYPAL_CLIENT_ID — PayPal app client ID
• PAYPAL_SECRET — PayPal app secret
• PAYPAL_MODE — sandbox or live

Journeys

The Payment System is the backbone of Journey 9:

• Journey 9: Billing & Payments

Key Source Files

• src/webhooks/billing.js — PayPal webhook route registration and event processing. Key exports: registerBillingRoutes() (line 12), processWebhookEvent() (line 198).
• src/actions/billing.js — Core billing action handlers: state transitions, reminder scheduling, commission calculation, and manual payment recording.

Payment State Machine

1. awaiting — payment expected, no action yet
2. grace — grace period active, soft reminder sent
3. staff_prompted — staff notified to follow up
4. patient_prompted — patient directly reminded
5. at_risk — escalation begins, account flagged
6. reconciliation — final resolution in progress
7. complete — payment confirmed and recorded

Escalation timeline: Day 3 warning → Day 7 suspend → Day 14 final → Day 30 cancel

Database Tables

• payments — payment records and current state
• billing_notifications — log of all reminder messages sent
• commissions — commission calculations per payment event
• accounting_sync_log — audit trail of all accounting sync actions
• accounting_chart_of_accounts — chart of accounts for categorization

Known Issues

None currently.