Add e-transfer destination email (studio default + offering/booking overrides)

The e-transfer destination is resolved at booking time (offering override ->
studio default) and frozen onto the payment, so each record keeps where the
student was directed. It can then be corrected per booking.

- StudioSettings: us_etransfer_email option + a Default e-transfer email field
  on the Studio Settings page.
- Offering: etransfer_email column/field (instructor override) across VO, repo,
  REST endpoint, admin controller, and form.
- Payment: etransfer_email column on the payment (frozen record) +
  PaymentRepository::updateEtransferEmail; PaymentService freezes it from the
  offering override or studio default at creation; booking/enrolment pass the
  offering override.
- My Lessons: instructors edit the e-transfer email per pending lesson payment
  (ownership-checked).
- Payments queue: studio admin can correct the email at confirmation (for when
  a student sends it to the wrong place).
- Docs updated.

Tests: Payment/Offering rows + PaymentService freezing. composer test (148),
cs, and PHPStan level 6 all pass.

Refs #7

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

src/Payment/Payment.php

@@ -40,6 +40,7 @@ class Payment {
 		public readonly string $currency = 'CAD',
 		public readonly string $method = self::METHOD_ETRANSFER,
 		public readonly string $status = self::STATUS_PENDING,
+		public readonly ?string $etransferEmail = null,
 		public readonly ?string $stripePaymentIntentId = null,
 		public readonly ?string $receiptNumber = null,
 		public readonly ?string $receiptSentAt = null,
@@ -57,6 +58,7 @@ class Payment {
 			currency:              $row->currency,
 			method:                $row->method,
 			status:                $row->status,
+			etransferEmail:        $row->etransfer_email,
 			stripePaymentIntentId: $row->stripe_payment_intent_id,
 			receiptNumber:         $row->receipt_number,
 			receiptSentAt:         $row->receipt_sent_at,
@@ -80,6 +82,7 @@ class Payment {
 			'student_id'        => $this->studentId,
 			'instructor_id'     => $this->instructorId,
 			'registration_type' => $this->registrationType,
+			'etransfer_email'   => $this->etransferEmail,
 			'registration_id'   => $this->registrationId,
 			'amount'            => $this->amount,
 			'currency'          => $this->currency,

src/Payment/PaymentController.php

@@ -20,9 +20,13 @@ class PaymentController {
 		if ( isset( $_POST['usc_action'] ) && check_admin_referer( 'usc_payment_action' ) ) {
 			// phpcs:ignore WordPress.Security.NonceVerification.Missing -- nonce checked above.
 			if ( 'mark_paid' === sanitize_key( wp_unslash( $_POST['usc_action'] ?? '' ) ) ) {
-				// phpcs:ignore WordPress.Security.NonceVerification.Missing
+				// phpcs:disable WordPress.Security.NonceVerification.Missing
 				$paymentId = absint( $_POST['payment_id'] ?? 0 );
+				$email     = sanitize_email( wp_unslash( $_POST['etransfer_email'] ?? '' ) );
+				// phpcs:enable WordPress.Security.NonceVerification.Missing
 				if ( $paymentId > 0 ) {
+					// Record the destination it was actually sent to before confirming.
+					$this->payments->updateEtransferEmail( $paymentId, '' !== $email ? $email : null );
 					$this->service->markPaid( $paymentId );
 				}
 			}
@@ -33,11 +37,12 @@ class PaymentController {
 				$student = get_userdata( $payment->studentId );
 
 				return [
-					'id'      => (int) $payment->id,
-					'student' => $student ? $student->display_name : (string) $payment->studentId,
-					'amount'  => number_format( $payment->amount, 2 ) . ' ' . $payment->currency,
-					'method'  => $payment->method,
-					'for'     => $payment->registrationType . ' #' . $payment->registrationId,
+					'id'              => (int) $payment->id,
+					'student'         => $student ? $student->display_name : (string) $payment->studentId,
+					'amount'          => number_format( $payment->amount, 2 ) . ' ' . $payment->currency,
+					'method'          => $payment->method,
+					'for'             => $payment->registrationType . ' #' . $payment->registrationId,
+					'etransfer_email' => (string) $payment->etransferEmail,
 				];
 			},
 			$this->payments->findPending()

src/Payment/PaymentRepository.php

@@ -23,18 +23,29 @@ class PaymentRepository {
 				'currency'                 => $payment->currency,
 				'method'                   => $payment->method,
 				'status'                   => $payment->status,
+				'etransfer_email'          => $payment->etransferEmail,
 				'stripe_payment_intent_id' => $payment->stripePaymentIntentId,
 				'receipt_number'           => $payment->receiptNumber,
 				'receipt_sent_at'          => $payment->receiptSentAt,
 				'paid_at'                  => $payment->paidAt,
 				'created_at'               => current_time( 'mysql' ),
 			],
-			[ '%d', '%d', '%s', '%d', '%f', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ]
+			[ '%d', '%d', '%s', '%d', '%f', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s', '%s' ]
 		);
 
 		return $this->db->insert_id;
 	}
 
+	public function updateEtransferEmail( int $id, ?string $email ): bool {
+		return false !== $this->db->update(
+			$this->table,
+			[ 'etransfer_email' => $email ],
+			[ 'id' => $id ],
+			[ '%s' ],
+			[ '%d' ]
+		);
+	}
+
 	public function findById( int $id ): ?Payment {
 		$row = $this->db->get_row(
 			$this->db->prepare( "SELECT * FROM {$this->table} WHERE id = %d", $id )

src/Payment/PaymentService.php

@@ -19,15 +19,17 @@ class PaymentService {
 		private ReceiptMailer $mailer,
 		private BookingRepository $bookings,
 		private EnrollmentRepository $enrollments,
+		private StudioSettings $settings,
 	) {}
 
 	/**
 	 * Create the payment for a new registration and link it. Comped students are
 	 * marked paid and confirmed immediately; everyone else gets a pending payment
-	 * (card via Stripe — coming soon; e-transfer confirmed manually). Returns null
-	 * when the registration has no price to charge.
+	 * (card via Stripe — coming soon; e-transfer confirmed manually). The
+	 * e-transfer destination is frozen now from the offering override or the studio
+	 * default. Returns null when the registration has no price to charge.
 	 */
-	public function createForRegistration( string $type, int $registrationId, int $studentId, int $instructorId, float $amount, string $currency ): ?Payment {
+	public function createForRegistration( string $type, int $registrationId, int $studentId, int $instructorId, float $amount, string $currency, ?string $offeringEtransferEmail = null ): ?Payment {
 		if ( $amount <= 0.0 ) {
 			return null;
 		}
@@ -35,6 +37,10 @@ class PaymentService {
 		$method = $this->resolver->resolve( $studentId );
 		$status = Payment::METHOD_COMP === $method ? Payment::STATUS_PAID : Payment::STATUS_PENDING;
 
+		$etransferEmail = null !== $offeringEtransferEmail && '' !== $offeringEtransferEmail
+			? $offeringEtransferEmail
+			: ( '' !== $this->settings->etransferEmail() ? $this->settings->etransferEmail() : null );
+
 		$id = $this->payments->insert(
 			new Payment(
 				studentId:        $studentId,
@@ -45,6 +51,7 @@ class PaymentService {
 				currency:         $currency,
 				method:           $method,
 				status:           $status,
+				etransferEmail:   $etransferEmail,
 			)
 		);
 

src/Payment/StudioSettings.php

@@ -7,10 +7,11 @@ use Unsupervised\Schedular\Auth\RoleManager;
 
 class StudioSettings {
 
-	public const OPT_PUBLISHABLE = 'us_stripe_publishable_key';
-	public const OPT_SECRET      = 'us_stripe_secret_key';
-	public const OPT_MODE        = 'us_stripe_mode';
-	public const OPT_CURRENCY    = 'us_currency';
+	public const OPT_PUBLISHABLE     = 'us_stripe_publishable_key';
+	public const OPT_SECRET          = 'us_stripe_secret_key';
+	public const OPT_MODE            = 'us_stripe_mode';
+	public const OPT_CURRENCY        = 'us_currency';
+	public const OPT_ETRANSFER_EMAIL = 'us_etransfer_email';
 
 	public function publishableKey(): string {
 		return (string) get_option( self::OPT_PUBLISHABLE, '' );
@@ -30,6 +31,14 @@ class StudioSettings {
 		return '' !== $currency ? strtoupper( $currency ) : 'CAD';
 	}
 
+	/**
+	 * The studio-default e-transfer destination email (used when an offering has
+	 * no override).
+	 */
+	public function etransferEmail(): string {
+		return (string) get_option( self::OPT_ETRANSFER_EMAIL, '' );
+	}
+
 	/**
 	 * Whether Stripe is configured. When false the platform falls back to
 	 * e-transfer billing and card processing is unavailable.
@@ -51,6 +60,7 @@ class StudioSettings {
 		$secretKey        = $this->secretKey();
 		$mode             = $this->mode();
 		$currency         = $this->currency();
+		$etransferEmail   = $this->etransferEmail();
 		$stripeConfigured = $this->isStripeConfigured();
 
 		include USC_PLUGIN_DIR . 'templates/admin/settings.php';
@@ -64,6 +74,7 @@ class StudioSettings {
 		update_option( self::OPT_SECRET, sanitize_text_field( wp_unslash( $_POST['secret_key'] ?? '' ) ) );
 		update_option( self::OPT_MODE, 'live' === $mode ? 'live' : 'test' );
 		update_option( self::OPT_CURRENCY, strtoupper( sanitize_text_field( wp_unslash( $_POST['currency'] ?? 'CAD' ) ) ) );
+		update_option( self::OPT_ETRANSFER_EMAIL, sanitize_email( wp_unslash( $_POST['etransfer_email'] ?? '' ) ) );
 		// phpcs:enable WordPress.Security.NonceVerification.Missing
 	}
 }