Add payments foundation (e-transfer/comp, Stripe config, receipts)

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>

tests/Unit/Payment/BillingMethodResolverTest.php

@@ -0,0 +1,58 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Payment\BillingMethodResolver;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\StudioSettings;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class BillingMethodResolverTest extends TestCase
+{
+    public function testPerStudentOverrideWins(): void
+    {
+        Functions\when('get_user_meta')->justReturn(Payment::METHOD_COMP);
+
+        $settings = Mockery::mock(StudioSettings::class);
+        $resolver = new BillingMethodResolver($settings);
+
+        self::assertSame(Payment::METHOD_COMP, $resolver->resolve(5));
+    }
+
+    public function testDefaultsToCardWhenStripeConfigured(): void
+    {
+        Functions\when('get_user_meta')->justReturn('');
+
+        $settings = Mockery::mock(StudioSettings::class);
+        $settings->shouldReceive('isStripeConfigured')->andReturn(true);
+        $resolver = new BillingMethodResolver($settings);
+
+        self::assertSame(Payment::METHOD_CARD, $resolver->resolve(5));
+    }
+
+    public function testDefaultsToEtransferWhenStripeNotConfigured(): void
+    {
+        Functions\when('get_user_meta')->justReturn('');
+
+        $settings = Mockery::mock(StudioSettings::class);
+        $settings->shouldReceive('isStripeConfigured')->andReturn(false);
+        $resolver = new BillingMethodResolver($settings);
+
+        self::assertSame(Payment::METHOD_ETRANSFER, $resolver->resolve(5));
+        self::assertSame(Payment::METHOD_ETRANSFER, $resolver->defaultMethod());
+    }
+
+    public function testInvalidOverrideFallsBackToDefault(): void
+    {
+        Functions\when('get_user_meta')->justReturn('bogus');
+
+        $settings = Mockery::mock(StudioSettings::class);
+        $settings->shouldReceive('isStripeConfigured')->andReturn(true);
+        $resolver = new BillingMethodResolver($settings);
+
+        self::assertSame(Payment::METHOD_CARD, $resolver->resolve(5));
+    }
+}

tests/Unit/Payment/PaymentRepositoryTest.php

@@ -0,0 +1,107 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\PaymentRepository;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PaymentRepositoryTest extends TestCase
+{
+    private \wpdb $db;
+    private PaymentRepository $repo;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->db         = Mockery::mock(\wpdb::class);
+        $this->db->prefix = 'wp_';
+        $this->repo       = new PaymentRepository($this->db);
+    }
+
+    public function testInsertReturnsId(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-08 12:00:00');
+
+        $this->db->shouldReceive('insert')
+            ->once()
+            ->with(
+                'wp_us_payments',
+                Mockery::on(static function (array $d): bool {
+                    return $d['student_id'] === 5
+                        && $d['amount'] === 35.00
+                        && $d['method'] === Payment::METHOD_ETRANSFER
+                        && $d['status'] === Payment::STATUS_PENDING;
+                }),
+                Mockery::type('array')
+            );
+        $this->db->insert_id = 50;
+
+        self::assertSame(50, $this->repo->insert(new Payment(5, 3, Payment::REG_LESSON, 12, 35.00)));
+    }
+
+    public function testMarkPaidUpdatesStatusAndReceipt(): void
+    {
+        Functions\expect('current_time')->with('mysql')->andReturn('2026-06-08 12:00:00');
+
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with(
+                'wp_us_payments',
+                Mockery::on(static fn (array $d): bool => $d['status'] === Payment::STATUS_PAID && $d['receipt_number'] === 'USC-50' && $d['paid_at'] === '2026-06-08 12:00:00'),
+                ['id' => 50],
+                ['%s', '%s', '%s'],
+                ['%d']
+            )
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->markPaid(50, 'USC-50'));
+    }
+
+    public function testFindByRegistrationReturnsPayment(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/registration_type = %s AND registration_id = %d/'), Payment::REG_LESSON, 12)
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_row')->andReturn($this->row());
+
+        self::assertInstanceOf(Payment::class, $this->repo->findByRegistration(Payment::REG_LESSON, 12));
+    }
+
+    public function testFindPendingMapsRows(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/status = %s/'), Payment::STATUS_PENDING)
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_results')->andReturn([$this->row()]);
+
+        self::assertCount(1, $this->repo->findPending());
+    }
+
+    private function row(): object
+    {
+        return (object) [
+            'id'                       => '50',
+            'student_id'               => '5',
+            'instructor_id'            => '3',
+            'registration_type'        => Payment::REG_LESSON,
+            'registration_id'          => '12',
+            'amount'                   => '35.00',
+            'currency'                 => 'CAD',
+            'method'                   => Payment::METHOD_ETRANSFER,
+            'status'                   => Payment::STATUS_PENDING,
+            'stripe_payment_intent_id' => null,
+            'receipt_number'           => null,
+            'receipt_sent_at'          => null,
+            'paid_at'                  => null,
+        ];
+    }
+}

tests/Unit/Payment/PaymentServiceTest.php

@@ -0,0 +1,117 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Booking\BookingRepository;
+use Unsupervised\Schedular\Booking\Lesson;
+use Unsupervised\Schedular\GroupClass\EnrollmentRepository;
+use Unsupervised\Schedular\Payment\BillingMethodResolver;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\PaymentRepository;
+use Unsupervised\Schedular\Payment\PaymentService;
+use Unsupervised\Schedular\Payment\ReceiptMailer;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PaymentServiceTest extends TestCase
+{
+    private PaymentRepository $payments;
+    private BillingMethodResolver $resolver;
+    private ReceiptMailer $mailer;
+    private BookingRepository $bookings;
+    private EnrollmentRepository $enrollments;
+    private PaymentService $service;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->payments    = Mockery::mock(PaymentRepository::class);
+        $this->resolver    = Mockery::mock(BillingMethodResolver::class);
+        $this->mailer      = Mockery::mock(ReceiptMailer::class);
+        $this->bookings    = Mockery::mock(BookingRepository::class);
+        $this->enrollments = Mockery::mock(EnrollmentRepository::class);
+
+        $this->service = new PaymentService(
+            $this->payments,
+            $this->resolver,
+            $this->mailer,
+            $this->bookings,
+            $this->enrollments
+        );
+
+        Functions\when('get_userdata')->justReturn(false);
+    }
+
+    private function payment(string $method, string $status, int $id): Payment
+    {
+        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', $method, $status, id: $id);
+    }
+
+    public function testFreeRegistrationCreatesNoPayment(): void
+    {
+        self::assertNull($this->service->createForRegistration(Payment::REG_LESSON, 12, 5, 3, 0.0, 'CAD'));
+    }
+
+    public function testEtransferStaysPending(): void
+    {
+        $this->resolver->shouldReceive('resolve')->with(5)->andReturn(Payment::METHOD_ETRANSFER);
+        $this->payments->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Payment $p): bool => $p->method === Payment::METHOD_ETRANSFER && $p->status === Payment::STATUS_PENDING))
+            ->andReturn(50);
+        $this->bookings->shouldReceive('setPaymentId')->once()->with(12, 50);
+        $this->payments->shouldReceive('findById')->with(50)->andReturn($this->payment(Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, 50));
+
+        // No markPaid / confirm for a pending e-transfer.
+        $result = $this->service->createForRegistration(Payment::REG_LESSON, 12, 5, 3, 35.00, 'CAD');
+
+        self::assertSame(Payment::STATUS_PENDING, $result->status);
+    }
+
+    public function testCompIsPaidAndConfirmsImmediately(): void
+    {
+        $this->resolver->shouldReceive('resolve')->with(5)->andReturn(Payment::METHOD_COMP);
+        $this->payments->shouldReceive('insert')
+            ->once()
+            ->with(Mockery::on(static fn (Payment $p): bool => $p->method === Payment::METHOD_COMP && $p->status === Payment::STATUS_PAID))
+            ->andReturn(60);
+        $this->bookings->shouldReceive('setPaymentId')->once()->with(12, 60);
+
+        $this->payments->shouldReceive('markPaid')->once()->with(60, 'USC-60')->andReturn(true);
+        $this->bookings->shouldReceive('updateStatus')->once()->with(12, Lesson::STATUS_CONFIRMED)->andReturn(true);
+        $this->payments->shouldReceive('findById')->with(60)->andReturn($this->payment(Payment::METHOD_COMP, Payment::STATUS_PAID, 60));
+        $this->mailer->shouldReceive('send')->andReturn(false);
+
+        $result = $this->service->createForRegistration(Payment::REG_LESSON, 12, 5, 3, 35.00, 'CAD');
+
+        self::assertSame(Payment::STATUS_PAID, $result->status);
+    }
+
+    public function testMarkPaidConfirmsAndReturnsTrue(): void
+    {
+        $this->payments->shouldReceive('findById')->with(70)->andReturn($this->payment(Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, 70));
+        $this->payments->shouldReceive('markPaid')->once()->with(70, 'USC-70')->andReturn(true);
+        $this->bookings->shouldReceive('updateStatus')->once()->with(12, Lesson::STATUS_CONFIRMED)->andReturn(true);
+        $this->mailer->shouldReceive('send')->andReturn(false);
+
+        self::assertTrue($this->service->markPaid(70));
+    }
+
+    public function testMarkPaidReturnsFalseWhenMissing(): void
+    {
+        $this->payments->shouldReceive('findById')->with(99)->andReturn(null);
+
+        self::assertFalse($this->service->markPaid(99));
+    }
+
+    public function testMarkPaidIdempotentWhenAlreadyPaid(): void
+    {
+        $this->payments->shouldReceive('findById')->with(80)->andReturn($this->payment(Payment::METHOD_ETRANSFER, Payment::STATUS_PAID, 80));
+
+        // Already paid → no markPaid/confirm calls.
+        self::assertTrue($this->service->markPaid(80));
+    }
+}

tests/Unit/Payment/PaymentTest.php

@@ -0,0 +1,63 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class PaymentTest extends TestCase
+{
+    public function testDefaults(): void
+    {
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00);
+
+        self::assertSame('CAD', $payment->currency);
+        self::assertSame(Payment::METHOD_ETRANSFER, $payment->method);
+        self::assertSame(Payment::STATUS_PENDING, $payment->status);
+        self::assertFalse($payment->isPaid());
+        self::assertNull($payment->id);
+    }
+
+    public function testConstants(): void
+    {
+        self::assertContains(Payment::METHOD_CARD, Payment::VALID_METHODS);
+        self::assertContains(Payment::METHOD_ETRANSFER, Payment::VALID_METHODS);
+        self::assertContains(Payment::METHOD_COMP, Payment::VALID_METHODS);
+        self::assertContains(Payment::STATUS_PAID, Payment::VALID_STATUSES);
+    }
+
+    public function testFromRowMapsCorrectly(): void
+    {
+        $payment = Payment::fromRow((object) [
+            'id'                       => '7',
+            'student_id'               => '5',
+            'instructor_id'            => '3',
+            'registration_type'        => Payment::REG_ENROLLMENT,
+            'registration_id'          => '12',
+            'amount'                   => '120.00',
+            'currency'                 => 'CAD',
+            'method'                   => Payment::METHOD_COMP,
+            'status'                   => Payment::STATUS_PAID,
+            'stripe_payment_intent_id' => null,
+            'receipt_number'           => 'USC-7',
+            'receipt_sent_at'          => null,
+            'paid_at'                  => '2026-06-08 10:00:00',
+        ]);
+
+        self::assertSame(7, $payment->id);
+        self::assertSame(120.00, $payment->amount);
+        self::assertSame(Payment::METHOD_COMP, $payment->method);
+        self::assertTrue($payment->isPaid());
+        self::assertSame('USC-7', $payment->receiptNumber);
+    }
+
+    public function testToArrayContainsExpectedKeys(): void
+    {
+        $arr = (new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, id: 7))->toArray();
+
+        foreach (['id', 'student_id', 'amount', 'currency', 'method', 'status', 'receipt_number'] as $key) {
+            self::assertArrayHasKey($key, $arr);
+        }
+    }
+}

tests/Unit/Payment/ReceiptMailerTest.php

@@ -0,0 +1,35 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Brain\Monkey\Functions;
+use Mockery;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\ReceiptMailer;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class ReceiptMailerTest extends TestCase
+{
+    public function testReturnsFalseWithoutRecipient(): void
+    {
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, receiptNumber: 'USC-1');
+
+        self::assertFalse((new ReceiptMailer())->send($payment, null));
+    }
+
+    public function testSendsReceiptToStudent(): void
+    {
+        Functions\expect('wp_mail')
+            ->once()
+            ->with('a@b.test', Mockery::type('string'), Mockery::type('string'))
+            ->andReturn(true);
+
+        $student             = Mockery::mock(\WP_User::class);
+        $student->user_email = 'a@b.test';
+
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, receiptNumber: 'USC-1');
+
+        self::assertTrue((new ReceiptMailer())->send($payment, $student));
+    }
+}