Journey 9: Billing & Payments — Oshun System Docs

STEP 1 Procedure Complete → Billing

Payment is due

After a procedure is completed (Journey 4), the patient's balance enters the billing system. Oshun's backend tracks every payment through a 6-hop state machine: awaiting → grace → staff_prompted → patient_prompted → at_risk → reconciliation → complete. The current state determines which actions Karen takes and when.

▶ Billing route registration and state machine ▶

Source files

src/webhooks/billing.js → registerBillingRoutes() (line 12)

What happens

When a procedure is marked complete, a payment record is created in awaiting state. registerBillingRoutes() mounts the PayPal and manual payment webhook handlers. The state machine advances automatically as time passes or as events (payment received, staff action, webhook callback) come in. Each state transition is logged for audit.

DB tables

payments, billing_notifications

STEP 2 Billing → Karen AI → Patient

Grace period and reminders

During the grace period, Karen sends a gentle, friendly reminder — never a harsh demand. Example: "Just a reminder about your Botox payment of $15,000 JMD. You can pay via the PayPal link below, or settle it at your next visit — whichever is easier for you." Patients can pay online via PayPal or in person at the clinic.

▶ Reminder delivery and payment options ▶

Source files

src/actions/billing.js

What happens

Karen's billing action generates a PayPal checkout link for the outstanding amount and sends it to the patient on their preferred channel (WhatsApp, Telegram, or Chatwoot widget). The payment state advances from awaiting to grace once the first reminder is sent. If no action is taken, the state progresses toward patient_prompted and eventually at_risk, triggering escalation.

Env vars

PAYPAL_CLIENT_ID, PAYPAL_SECRET, PAYPAL_MODE

STEP 3 PayPal/Backend → Webhook

Payment received

When the patient pays — either through the PayPal link or recorded manually at the clinic — the payment status moves to complete. Karen sends a confirmation to the patient ("Got it! Your payment is confirmed — thank you!") and notifies staff via Telegram so they have a clean record.

▶ Payment webhook processing ▶

Source files

src/webhooks/billing.js → processWebhookEvent() (line 198)

What happens

processWebhookEvent() handles the PAYMENT.SALE.COMPLETED event from PayPal. It verifies the webhook signature, matches the payment to the correct patient record, and updates the payments row to complete. For manual clinic payments, staff records via the backend trigger the same state transition. Both paths log to accounting_sync_log for reconciliation.

DB tables

payments, accounting_sync_log

STEP 4 Billing → Accounting

Commission calculated

Once payment is confirmed, the system automatically calculates the commission due. Under the Oshun deal, IrieVybz earns a 10% commission on procedures on top of the $500/mo base retainer. This is calculated per payment and logged immediately — no manual spreadsheets, no end-of-month scramble.

▶ Commission calculation and accounting log ▶

Source files

src/webhooks/billing.js — commission calculation (inline with payment processing)

What happens

On payment completion, the billing module applies the 10% commission rate to the procedure amount and writes a commission record. The chart of accounts entry is created in accounting_chart_of_accounts for each transaction. Matthew can query commission totals at any time via Telegram ("Karen, what's my commission this month?").

DB tables

commissions, accounting_chart_of_accounts

Deal terms

Oshun: $500/mo base retainer + 10% commission on all procedure payments processed through the system.

STEP 5 Billing → Escalation

Escalation cascade (if unpaid)

If a balance remains unpaid, the system escalates through four stages — notifying both the patient and Oshun staff at each point. Day 3: gentle warning. Day 7: service suspension warning. Day 14: final notice. Day 30: account cancellation. Karen handles patient-facing messages; staff get Telegram alerts so they can intervene before it reaches the final stage.

▶ Escalation stages and BullMQ scheduling ▶

Source files

src/actions/billing.js — escalation stage definitions
BullMQ scheduled jobs (via src/scheduler.js)

What happens

Each escalation stage is a BullMQ delayed job queued at payment creation. As each deadline passes without a complete state, the next job fires. Karen delivers the patient message (tone escalates from warm to firm across stages). Staff receive a Telegram alert at each step so they can intervene. If payment is received at any point, all pending escalation jobs are cancelled immediately.

Escalation timeline

Day 3 — Warning reminder
Day 7 — Service suspension warning
Day 14 — Final notice
Day 30 — Account cancellation

DB tables

billing_notifications, payments