thatguygriff
6c4097b385
CI / Tests (PHP 8.1) (pull_request) Successful in 45s
CI / Tests (PHP 8.3) (pull_request) Successful in 50s
CI / No Debug Code (pull_request) Successful in 3s
CI / Coding Standards (pull_request) Successful in 1m2s
CI / Tests (PHP 8.2) (pull_request) Successful in 1m0s
CI / PHPStan (pull_request) Successful in 1m4s
CI / Build Plugin Zip (pull_request) Has been skipped
Implements the payments foundation for #7. Without Stripe credentials everything works on e-transfer (pending payment confirmed by a studio admin); when Stripe keys are configured the default flips to credit card. Per-student override (card/etransfer/comp) is set on the student detail. - Schema: us_payments (amount DECIMAL dollars, method, status, receipt, stripe intent id). - src/Payment/: Payment VO, PaymentRepository, StudioSettings (Stripe options + isStripeConfigured + settings page), BillingMethodResolver (per-student override; default card if configured else etransfer), ReceiptMailer, PaymentService (create at registration, link payment_id, comp->paid+confirm, markPaid->confirm+receipt), PaymentController (e-transfer confirmation queue), PaymentEndpoint (PATCH /payments/{id}). - Booking + enrolment create the payment from the offering price; comp auto-confirms the lesson; setPaymentId on both repositories. - Admin: Studio Settings + Payments menus (manage_billing); per-student billing method on the student detail page. - Docs: payments.md + README updated. Deferred to a follow-up: the live Stripe card charge (PaymentIntent + Stripe.js Elements + webhook + stripe/stripe-php). Until then a card payment is created pending and confirmed like an e-transfer. Tests: tests/Unit/Payment/ (VO, repository, resolver, service, mailer). composer test (147), cs, and PHPStan level 6 all pass. Refs #7 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
92 lines
6.0 KiB
Markdown
92 lines
6.0 KiB
Markdown
# 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
|
|
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, and
|
|
> integration into booking/enrolment (a registration's `payment_id` is linked;
|
|
> comp auto-confirms; e-transfer stays pending until confirmed).
|
|
> **Deferred to a follow-up:** the live Stripe card charge (PaymentIntent +
|
|
> Stripe.js Elements + webhook + `stripe/stripe-php`). Until then a `card`
|
|
> payment is created `pending` and can be confirmed like an e-transfer.
|
|
|
|
## 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_mode` | `test` or `live` |
|
|
| `us_currency` | Default ISO 4217 currency, e.g. `CAD` |
|
|
|
|
## 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 |
|
|
|
|
## 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` |
|
|
| `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 |
|
|
|
|
## Payment Flow
|
|
1. During registration the front-end calls `POST /payments/intent`, which 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.
|
|
|
|
## 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`
|
|
|
|
## Tests
|
|
- `tests/Unit/Payment/PaymentRepositoryTest.php`
|
|
- `tests/Unit/Payment/PaymentTest.php`
|
|
- `tests/Unit/Payment/StripeGatewayTest.php`
|
|
- `tests/Unit/Payment/ReceiptMailerTest.php`
|