Add live Stripe card charges (PaymentIntent + Elements + webhook)

Completes the deferred half of payments: real credit-card processing on
top of the existing ledger/e-transfer/comp foundation.

- StripeGateway wraps stripe/stripe-php: creates idempotent PaymentIntents
  (amount in cents, registration ids in metadata) and verifies webhook
  signatures. Stripe calls sit behind protected seams for unit testing.
- PaymentService::createIntent resolves the client-side step for a new
  registration (card → client secret; e-transfer → display data; comp →
  none) with caller-ownership enforcement.
- PaymentService::handleWebhook finalises a payment exactly once on
  payment_intent.succeeded (mark paid → confirm → receipt) and marks it
  failed on payment_intent.payment_failed.
- PaymentEndpoint: POST /payments/intent (book_lesson) and public,
  signature-verified POST /payments/webhook.
- PaymentRepository: setStripeIntentId / findByStripeIntentId.
- StudioSettings: us_stripe_webhook_secret option, with the webhook URL
  and required events surfaced on the settings page.
- Front end: shared payment.js mounts Stripe Payment Elements and confirms
  the card (or shows e-transfer instructions); Stripe.js enqueued only when
  configured. Wired into booking and group-class flows.

Tests: new StripeGatewayTest; PaymentService card-intent + webhook cases;
repository coverage. composer test/lint/cs all green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

tests/Unit/Payment/PaymentRepositoryTest.php

@@ -98,6 +98,42 @@ class PaymentRepositoryTest extends TestCase
         self::assertCount(0, $this->repo->findPaidBetween('2026-06-01 00:00:00', '2026-07-01 00:00:00'));
     }
 
+    public function testSetStripeIntentIdUpdatesRow(): void
+    {
+        $this->db->shouldReceive('update')
+            ->once()
+            ->with(
+                'wp_us_payments',
+                ['stripe_payment_intent_id' => 'pi_123'],
+                ['id' => 50],
+                ['%s'],
+                ['%d']
+            )
+            ->andReturn(1);
+
+        self::assertTrue($this->repo->setStripeIntentId(50, 'pi_123'));
+    }
+
+    public function testFindByStripeIntentIdReturnsPayment(): void
+    {
+        $this->db->shouldReceive('prepare')
+            ->once()
+            ->with(Mockery::pattern('/stripe_payment_intent_id = %s/'), 'pi_123')
+            ->andReturn('SELECT ...');
+
+        $this->db->shouldReceive('get_row')->andReturn($this->row());
+
+        self::assertInstanceOf(Payment::class, $this->repo->findByStripeIntentId('pi_123'));
+    }
+
+    public function testFindByStripeIntentIdReturnsNullWhenMissing(): void
+    {
+        $this->db->shouldReceive('prepare')->andReturn('SELECT ...');
+        $this->db->shouldReceive('get_row')->andReturn(null);
+
+        self::assertNull($this->repo->findByStripeIntentId('pi_missing'));
+    }
+
     public function testFindByRegistrationReturnsPayment(): void
     {
         $this->db->shouldReceive('prepare')

tests/Unit/Payment/PaymentServiceTest.php

@@ -13,6 +13,7 @@ use Unsupervised\Schedular\Payment\Payment;
 use Unsupervised\Schedular\Payment\PaymentRepository;
 use Unsupervised\Schedular\Payment\PaymentService;
 use Unsupervised\Schedular\Payment\ReceiptMailer;
+use Unsupervised\Schedular\Payment\StripeGateway;
 use Unsupervised\Schedular\Payment\StudioSettings;
 use Unsupervised\Schedular\Tests\Unit\TestCase;
 
@@ -24,6 +25,7 @@ class PaymentServiceTest extends TestCase
     private BookingRepository $bookings;
     private EnrollmentRepository $enrollments;
     private StudioSettings $settings;
+    private StripeGateway $stripe;
     private PaymentService $service;
 
     protected function setUp(): void
@@ -36,6 +38,7 @@ class PaymentServiceTest extends TestCase
         $this->bookings    = Mockery::mock(BookingRepository::class);
         $this->enrollments = Mockery::mock(EnrollmentRepository::class);
         $this->settings    = Mockery::mock(StudioSettings::class);
+        $this->stripe      = Mockery::mock(StripeGateway::class);
         $this->settings->shouldReceive('etransferEmail')->andReturn('');
         $this->settings->shouldReceive('hstRate')->andReturn(0.0)->byDefault();
 
@@ -45,7 +48,8 @@ class PaymentServiceTest extends TestCase
             $this->mailer,
             $this->bookings,
             $this->enrollments,
-            $this->settings
+            $this->settings,
+            $this->stripe
         );
 
         Functions\when('get_userdata')->justReturn(false);
@@ -166,4 +170,125 @@ class PaymentServiceTest extends TestCase
         // Already paid → no markPaid/confirm calls.
         self::assertTrue($this->service->markPaid(80));
     }
+
+    public function testCreateIntentForCardReturnsClientSecret(): void
+    {
+        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 12)
+            ->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PENDING, 90));
+
+        $intent = \Stripe\PaymentIntent::constructFrom(['id' => 'pi_abc', 'client_secret' => 'pi_abc_secret']);
+        $this->stripe->shouldReceive('createIntent')->once()
+            ->with(Mockery::on(static fn (Payment $p): bool => $p->id === 90))
+            ->andReturn($intent);
+        $this->payments->shouldReceive('setStripeIntentId')->once()->with(90, 'pi_abc')->andReturn(true);
+        $this->settings->shouldReceive('publishableKey')->andReturn('pk_test_123');
+
+        $result = $this->service->createIntent(Payment::REG_LESSON, 12, 5);
+
+        self::assertSame('card', $result['method']);
+        self::assertSame('pi_abc_secret', $result['client_secret']);
+        self::assertSame('pk_test_123', $result['publishable_key']);
+    }
+
+    public function testCreateIntentForEtransferReturnsDisplayDataWithoutStripe(): void
+    {
+        $payment = new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_ETRANSFER, Payment::STATUS_PENDING, etransferEmail: 'pay@studio.test', id: 91);
+        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 12)->andReturn($payment);
+
+        $this->stripe->shouldNotReceive('createIntent');
+
+        $result = $this->service->createIntent(Payment::REG_LESSON, 12, 5);
+
+        self::assertSame('etransfer', $result['method']);
+        self::assertSame('pay@studio.test', $result['etransfer_email']);
+        self::assertArrayNotHasKey('client_secret', $result);
+    }
+
+    public function testCreateIntentReturnsNullWhenNotOwner(): void
+    {
+        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 12)
+            ->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PENDING, 90));
+
+        // Student 999 does not own payment whose studentId is 5.
+        self::assertNull($this->service->createIntent(Payment::REG_LESSON, 12, 999));
+    }
+
+    public function testCreateIntentReturnsNullWhenNoPayment(): void
+    {
+        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 12)->andReturn(null);
+
+        self::assertNull($this->service->createIntent(Payment::REG_LESSON, 12, 5));
+    }
+
+    public function testCreateIntentReturnsNullWhenStripeFails(): void
+    {
+        $this->payments->shouldReceive('findByRegistration')->with(Payment::REG_LESSON, 12)
+            ->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PENDING, 90));
+        $this->stripe->shouldReceive('createIntent')->once()->andReturn(null);
+
+        self::assertNull($this->service->createIntent(Payment::REG_LESSON, 12, 5));
+    }
+
+    public function testHandleWebhookInvalidSignatureReturnsFalse(): void
+    {
+        $this->stripe->shouldReceive('verifyWebhook')->with('{}', 'bad-sig')->andReturn(null);
+
+        self::assertFalse($this->service->handleWebhook('{}', 'bad-sig'));
+    }
+
+    public function testHandleWebhookSucceededFinalizesPayment(): void
+    {
+        $event = $this->intentEvent('payment_intent.succeeded', 'pi_ok');
+        $this->stripe->shouldReceive('verifyWebhook')->andReturn($event);
+
+        $this->payments->shouldReceive('findByStripeIntentId')->with('pi_ok')
+            ->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PENDING, 90));
+
+        $this->payments->shouldReceive('markPaid')->once()->with(90, 'USC-90')->andReturn(true);
+        $this->bookings->shouldReceive('updateStatus')->once()->with(12, Lesson::STATUS_CONFIRMED)->andReturn(true);
+        $this->payments->shouldReceive('findById')->with(90)->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PAID, 90));
+        $this->mailer->shouldReceive('send')->andReturn(false);
+
+        self::assertTrue($this->service->handleWebhook('{}', 'sig'));
+    }
+
+    public function testHandleWebhookSucceededIdempotentWhenAlreadyPaid(): void
+    {
+        $event = $this->intentEvent('payment_intent.succeeded', 'pi_ok');
+        $this->stripe->shouldReceive('verifyWebhook')->andReturn($event);
+
+        $this->payments->shouldReceive('findByStripeIntentId')->with('pi_ok')
+            ->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PAID, 90));
+
+        // Already paid → no markPaid/confirm.
+        self::assertTrue($this->service->handleWebhook('{}', 'sig'));
+    }
+
+    public function testHandleWebhookFailedMarksFailed(): void
+    {
+        $event = $this->intentEvent('payment_intent.payment_failed', 'pi_bad');
+        $this->stripe->shouldReceive('verifyWebhook')->andReturn($event);
+
+        $this->payments->shouldReceive('findByStripeIntentId')->with('pi_bad')
+            ->andReturn($this->payment(Payment::METHOD_CARD, Payment::STATUS_PENDING, 90));
+        $this->payments->shouldReceive('updateStatus')->once()->with(90, Payment::STATUS_FAILED)->andReturn(true);
+
+        self::assertTrue($this->service->handleWebhook('{}', 'sig'));
+    }
+
+    public function testHandleWebhookAcknowledgesUnknownIntent(): void
+    {
+        $event = $this->intentEvent('payment_intent.succeeded', 'pi_unknown');
+        $this->stripe->shouldReceive('verifyWebhook')->andReturn($event);
+        $this->payments->shouldReceive('findByStripeIntentId')->with('pi_unknown')->andReturn(null);
+
+        self::assertTrue($this->service->handleWebhook('{}', 'sig'));
+    }
+
+    private function intentEvent(string $type, string $intentId): \Stripe\Event
+    {
+        $intent = \Stripe\PaymentIntent::constructFrom(['id' => $intentId, 'object' => 'payment_intent']);
+
+        return \Stripe\Event::constructFrom(['type' => $type, 'data' => ['object' => $intent]]);
+    }
 }

tests/Unit/Payment/StripeGatewayTest.php

@@ -0,0 +1,111 @@
+<?php
+declare(strict_types=1);
+
+namespace Unsupervised\Schedular\Tests\Unit\Payment;
+
+use Mockery;
+use Unsupervised\Schedular\Payment\Payment;
+use Unsupervised\Schedular\Payment\StripeGateway;
+use Unsupervised\Schedular\Payment\StudioSettings;
+use Unsupervised\Schedular\Tests\Unit\TestCase;
+
+class StripeGatewayTest extends TestCase
+{
+    private StudioSettings $settings;
+
+    protected function setUp(): void
+    {
+        parent::setUp();
+
+        $this->settings = Mockery::mock(StudioSettings::class);
+    }
+
+    private function partialGateway(): StripeGateway
+    {
+        return Mockery::mock(StripeGateway::class, [$this->settings])
+            ->makePartial()
+            ->shouldAllowMockingProtectedMethods();
+    }
+
+    private function payment(): Payment
+    {
+        return new Payment(5, 3, Payment::REG_LESSON, 12, 35.00, 'CAD', Payment::METHOD_CARD, Payment::STATUS_PENDING, id: 90);
+    }
+
+    public function testCreateIntentReturnsNullWhenNotConfigured(): void
+    {
+        $this->settings->shouldReceive('isStripeConfigured')->andReturn(false);
+
+        $gateway = new StripeGateway($this->settings);
+
+        self::assertNull($gateway->createIntent($this->payment()));
+    }
+
+    public function testCreateIntentSendsAmountInCentsAndReturnsIntent(): void
+    {
+        $this->settings->shouldReceive('isStripeConfigured')->andReturn(true);
+
+        $intent  = \Stripe\PaymentIntent::constructFrom(['id' => 'pi_1', 'client_secret' => 'cs_1']);
+        $gateway = $this->partialGateway();
+        $gateway->shouldReceive('paymentIntentsCreate')
+            ->once()
+            ->with(
+                Mockery::on(static fn (array $p): bool => $p['amount'] === 3500
+                    && $p['currency'] === 'cad'
+                    && $p['metadata']['payment_id'] === '90'),
+                Mockery::on(static fn (array $o): bool => $o['idempotency_key'] === 'usc-payment-90')
+            )
+            ->andReturn($intent);
+
+        self::assertSame('pi_1', $gateway->createIntent($this->payment())->id);
+    }
+
+    public function testCreateIntentReturnsNullOnStripeError(): void
+    {
+        $this->settings->shouldReceive('isStripeConfigured')->andReturn(true);
+
+        $gateway = $this->partialGateway();
+        $gateway->shouldReceive('paymentIntentsCreate')->once()->andThrow(new \RuntimeException('declined'));
+
+        self::assertNull($gateway->createIntent($this->payment()));
+    }
+
+    public function testVerifyWebhookReturnsNullWithoutSecret(): void
+    {
+        $this->settings->shouldReceive('webhookSecret')->andReturn('');
+
+        $gateway = new StripeGateway($this->settings);
+
+        self::assertNull($gateway->verifyWebhook('{}', 'sig'));
+    }
+
+    public function testVerifyWebhookReturnsNullWithoutSignatureHeader(): void
+    {
+        $this->settings->shouldReceive('webhookSecret')->andReturn('whsec_123');
+
+        $gateway = new StripeGateway($this->settings);
+
+        self::assertNull($gateway->verifyWebhook('{}', ''));
+    }
+
+    public function testVerifyWebhookReturnsNullOnInvalidSignature(): void
+    {
+        $this->settings->shouldReceive('webhookSecret')->andReturn('whsec_123');
+
+        $gateway = $this->partialGateway();
+        $gateway->shouldReceive('constructEvent')->once()->andThrow(new \RuntimeException('bad signature'));
+
+        self::assertNull($gateway->verifyWebhook('{}', 'sig'));
+    }
+
+    public function testVerifyWebhookReturnsEventOnSuccess(): void
+    {
+        $this->settings->shouldReceive('webhookSecret')->andReturn('whsec_123');
+
+        $event   = \Stripe\Event::constructFrom(['type' => 'payment_intent.succeeded']);
+        $gateway = $this->partialGateway();
+        $gateway->shouldReceive('constructEvent')->once()->with('{payload}', 'sig', 'whsec_123')->andReturn($event);
+
+        self::assertSame('payment_intent.succeeded', $gateway->verifyWebhook('{payload}', 'sig')->type);
+    }
+}