unsupervised-scheduler/docs/features/payments.md

Feature: Payments

Overview

Payment is taken at registration. When Stripe is not configured the platform falls back to e-transfer — a pending payment a studio admin marks received — so everything works without any credentials. When Stripe is configured the default rail becomes the credit card. The studio admin can override any student's method (card / e-transfer / comp). Single bookings are charged once; weekly reservations and group classes are charged the full term upfront (a full_term price once, or a per-lesson one_time price × the occurrences reserved — see lesson-booking.md). A numbered receipt is emailed automatically when a payment is marked paid.

Implemented: the payment ledger, studio settings, method resolution (e-transfer default with no Stripe; card default when configured; per-student override), the e-transfer/comp flow with admin confirmation + receipts, integration into booking/enrolment (a registration's payment_id is linked; comp auto-confirms; e-transfer stays pending until confirmed), and the live Stripe card charge — a PaymentIntent created on POST /payments/intent, confirmed in the browser with Stripe.js Payment Elements, and finalised by the POST /payments/webhook handler (signature-verified) on payment_intent.succeeded. Uses the stripe/stripe-php SDK.

Stripe Configuration

Stripe credentials live in WordPress options, managed on the Studio Settings page (manage_billing, studio admin only):

Option	Notes
us_stripe_publishable_key	Stripe publishable key
us_stripe_secret_key	Stripe secret key
us_stripe_webhook_secret	Webhook signing secret (whsec_…)
us_stripe_mode	test or live
us_currency	Default ISO 4217 currency, e.g. CAD
us_etransfer_email	Studio-default e-transfer destination
us_hst_rate	Default HST/tax percentage, e.g. 13

HST / Tax

A studio-default HST rate (percentage) is configured on Studio Settings (us_hst_rate, manage_billing). At booking the rate is frozen onto the payment (us_payments.tax_rate) and the tax is computed against the pre-tax subtotal (tax_amount = round(amount × rate / 100, 2)). The billed total is amount + tax_amount (Payment::total()). Comped registrations are never taxed (rate and amount are 0).

The rate is overridable per booking on My Lessons (instructor) while the payment is still unpaid; saving recomputes tax_amount from the current subtotal (PaymentRepository::updateTax). Receipts break out subtotal, HST, and total when tax applies.

Per-Student Billing Method

Each student's billing method is stored in user meta us_payment_method, set by the studio admin (Students → student detail → Billing method). When unset, the studio default applies — card if Stripe is configured, otherwise etransfer (BillingMethodResolver):

Method	Behaviour
card	Charged immediately via Stripe; payment paid on success
etransfer	Payment row created pending; admin marks it paid when funds arrive
comp	No charge; registration is confirmed immediately, no payment row required

E-transfer Destination Email

Where students send e-transfers is resolved and frozen onto the payment at booking time (us_payments.etransfer_email), so each record keeps the destination the student was given. Resolution at creation:

1. Offering override — us_offerings.etransfer_email, set by the instructor on the offering.
2. Studio default — the us_etransfer_email option (Studio Settings, manage_billing).

After booking, the destination on a payment can be corrected per booking:

• My Lessons — the instructor edits the e-transfer email for a pending lesson payment.
• Payments queue — when marking an e-transfer received, the studio admin can update the email it was actually sent to before confirming.

Data Model — {prefix}us_payments

Column	Type	Notes
id	BIGINT UNSIGNED	Primary key
student_id	BIGINT UNSIGNED	WordPress user ID
instructor_id	BIGINT UNSIGNED	WordPress user ID (denormalised for reporting)
registration_type	VARCHAR(20)	lesson or enrollment
registration_id	BIGINT UNSIGNED	FK → us_lessons.id or us_group_enrollments.id
amount	DECIMAL(10,2)	Charged amount in dollars (matches the offering price)
currency	VARCHAR(3)	ISO 4217, e.g. CAD
method	VARCHAR(20)	card / etransfer / comp
status	VARCHAR(20)	pending / paid / failed / refunded
tax_rate	DECIMAL(5,2)	HST rate % frozen at booking; editable until paid
tax_amount	DECIMAL(10,2)	Computed tax in dollars (amount × tax_rate / 100)
due_date	DATE	When a scheduled payment is due; NULL = due at registration (Payment::isScheduled())
period_key	VARCHAR(20)	Scheduled-billing dedup key: session date (weekly) or YYYY-MM (monthly); NULL otherwise
notice_batch	VARCHAR(32)	Shared reference for the payments one due-notice email covers, so a lump-sum e-transfer reconciles to them; NULL otherwise
etransfer_email	VARCHAR(191)	Frozen e-transfer destination; editable until confirmed
stripe_payment_intent_id	VARCHAR(255)	Stripe PaymentIntent id; NULL for e-transfer / comp
receipt_number	VARCHAR(50)	Sequential receipt id; set when paid
receipt_sent_at	DATETIME	When the receipt email was sent; NULL until sent
created_at	DATETIME	Insertion time
paid_at	DATETIME	When marked paid; NULL otherwise

Price Display and the Pay Agreement

Every price a student is shown on the front end carries its cadence — the offering's billing_mode in the words the student needs:

billing_mode	Shown as	Explained beneath as
one_time	at booking	Charged once, when you book.
full_term	up front	Charged once, up front, for the whole term.
weekly	weekly	Charged for each lesson, 24 hours before it starts.
monthly	per lesson monthly / monthly	Charged on the 1st of each month, for that month's lessons.

So a lesson type reads 50.00 CAD at booking in the booking form's type picker, and a group class card reads 120.00 CAD up front. A free offering shows Free.

monthly reads differently per offering kind. A private lesson's monthly charge is that month's lessons × the fee, so the fee is quoted per lesson (50.00 CAD per lesson monthly). A group class is enrolled in once, as one schedule, so its figure is quoted as it stands (120.00 CAD monthly) — see isPerLessonMonthly() in assets/js/pricing.js.

Caveat. ScheduledBillingRunner::billGroupMonthly() bills a monthly group class price × sessions in the month, the same per-session multiplication used for private lessons — so a class meeting weekly is charged roughly four times the quoted 120.00 CAD monthly figure. The display deliberately quotes the price as a monthly figure; closing the gap means either billing a monthly group class once per month regardless of session count, or restoring the per-lesson wording for group classes too.

Before a booking or enrolment can be submitted, the form shows the price again as a summary block with a required agreement checkbox — the second confirmation, distinct from the policy acceptances above it:

☐ I agree to pay 56.50 CAD at booking.

The agreed figure is the amount actually billed, so the studio HST rate is added to it (usScheduler.taxRate, localized from us_hst_rate) and broken out above the checkbox — matching the total Payment::total() charges. A comped student is not taxed and is not charged at all, so for them the quoted figure is an upper bound. A free offering has nothing to agree to and shows no block.

Cadence-specific wording:

• Weekly reservation of a one_time lesson type — the fee is charged once per week claimed, so the agreement states the per-lesson amount and the total as a ceiling ("up to 12 lessons, 678.00 CAD in total"). The occurrence count mirrors BookingEndpoint::MAX_WEEKLY_OCCURRENCES; a slot another student takes first is simply not claimed, so the real charge can come in under it.
• weekly / monthly — nothing is taken at registration, so the agreement is to the recurring charge: "I agree to pay 56.50 CAD per lesson, billed monthly." A monthly group class agrees to its monthly figure instead ("I agree to pay 138.00 CAD monthly."), matching how its price is quoted on the card.

All of this lives in assets/js/pricing.js (window.usPricing), shared by the booking and group-class flows so a price reads the same wherever it is met. The script is registered as us-scheduler-pricing and is a dependency of both us-scheduler and us-scheduler-group.

Payment Flow

1. During registration the front-end calls POST /payments/intent — but only when the registration response carried a payment summary (unpriced registrations return payment: null and skip the payment step). The intent call creates a Stripe PaymentIntent for a card student and returns the client secret. (etransfer returns a pending payment; comp returns none.)
2. The browser confirms the card payment with Stripe.
3. Stripe calls POST /payments/webhook; on payment_intent.succeeded the payment is marked paid, paid_at is stamped, and the linked lesson/enrolment is confirmed.
4. On transition to paid, ReceiptMailer assigns a receipt_number, emails the student a receipt, and stamps receipt_sent_at.
5. For an e-transfer, the studio admin later calls PATCH /payments/{id} to mark it paid, which triggers the same confirmation + receipt.

Scheduled Billing (weekly / monthly)

weekly and monthly offerings are not charged at registration. The booking / enrolment succeeds with payment: null; the lesson is confirmed (or the enrolment stays active) immediately, and payments are generated later by the daily us_generate_due_payments cron scan (Payment\ScheduledBillingRunner). Each generated payment carries a due_date and period_key, flows through the same PaymentService::createForRegistration (so HST, method resolution, e-transfer freezing and comp auto-pay are identical), and the student is emailed one consolidated itemised notice per scan (Payment\PaymentDueMailer). Because these payments are scheduled, PaymentService::voidPending never voids them — cancelling one lesson leaves a shared monthly charge (and every other lesson it covers) untouched, and never rebills. Full model, dedup, and the four generation cases are documented in scheduled-billing.md.

Cancelling a lesson that was already paid issues the student an account credit for that lesson's share of what they paid; the next daily scan applies any available credit against their due charges (reducing us_payments.credit_applied → Payment::netDue()) before emailing the notice. See credits.md.

REST API

Method	Endpoint	Permission
POST	/wp-json/us-scheduler/v1/payments/intent	book_lesson
POST	/wp-json/us-scheduler/v1/payments/webhook	Public (Stripe signature verified)
PATCH	/wp-json/us-scheduler/v1/payments/{id}	manage_billing

See payment-reporting.md for the monthly report and CSV export endpoints.

Implementation

• Repository: Unsupervised\Schedular\Payment\PaymentRepository
• Model: Unsupervised\Schedular\Payment\Payment
• Stripe gateway: Unsupervised\Schedular\Payment\StripeGateway
• Receipts: Unsupervised\Schedular\Payment\ReceiptMailer
• Settings page: Unsupervised\Schedular\Payment\StudioSettings
• REST endpoint: Unsupervised\Schedular\Payment\PaymentEndpoint
• Front-end price display + pay agreement: assets/js/pricing.js (window.usPricing), registered and localized with taxRate by Unsupervised\Schedular\ShortcodeRegistrar

Tests

• tests/Unit/ShortcodeRegistrarTest.php (pricing helper registration + localized taxRate)
• tests/Unit/Payment/PaymentRepositoryTest.php
• tests/Unit/Payment/PaymentTest.php
• tests/Unit/Payment/StripeGatewayTest.php
• tests/Unit/Payment/ReceiptMailerTest.php