TRU-74: document retired direct Stripe payment-link route in OpenAPI

The POST /modules/stripe/invoice endpoint was retired in PR #327 (always
returns HTTP 410 with code stripe_email_payment_disabled). This patch
aligns the public OpenAPI spec with the new behaviour, documents the
legacy DELETE /modules/stripe/invoice cleanup route, and adds a unit
test that guards the documentation so future contributors cannot
silently un-retire the payment-link creation route.

Refs: TRU-74 / DRIFT 13

services/nginx/app/openapi.yaml

@@ -10344,8 +10344,11 @@ paths:
     post:
       tags:
         - Modules
-      summary: Create Stripe invoice
-      description: Create an invoice in Stripe
+      summary: Create Stripe invoice (retired - TRU-74 / DRIFT 13)
+      description: |
+        Retired in favour of in-store card payments. Always returns HTTP 410
+        with `code: stripe_email_payment_disabled` so the POS can fall back
+        to the standard card-payment flow.
       operationId: createStripeInvoice
       requestBody:
         required: false
@@ -10353,11 +10356,41 @@ paths:
           application/json:
             schema: {}
       responses:
-        '201':
-          description: Stripe invoice created successfully
+        '410':
+          description: Direct Stripe payment links by email are no longer available
           content:
             application/json:
-              schema: {}
+              schema:
+                type: object
+                properties:
+                  code:
+                    type: string
+                    example: stripe_email_payment_disabled
+                  message:
+                    type: string
+    delete:
+      tags:
+        - Modules
+      summary: Cancel/clean up a legacy Stripe hosted invoice
+      description: |
+        Void a pre-existing Stripe hosted invoice that was created before
+        direct payment links were retired from POS (TRU-74 / DRIFT 13).
+        Card payments created via the new flow are not affected and use
+        the standard payment-intent lifecycle instead.
+      operationId: cancelLegacyStripeInvoice
+      parameters:
+        - name: order_id
+          in: query
+          required: true
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Legacy Stripe hosted invoice was voided
+          content:
+            application/json:
+              schema:
+                type: object
 
   /modules/stripe/terminal/readers:
     get:

services/nginx/app/tests/Unit/Stripe/ModuleStripePaymentLinkRetirementOpenApiTest.php

@@ -0,0 +1,28 @@
+<?php
+
+it('documents the retired Stripe hosted invoice creation route in the public OpenAPI spec (TRU-74)', function (): void {
+    $openApiFile = dirname(__DIR__, 3) . '/openapi.yaml';
+    $contents = file_get_contents($openApiFile);
+
+    expect($contents)->not->toBeFalse();
+
+    $needle = "  /modules/stripe/invoice:";
+    $start = strpos($contents, $needle);
+    expect($start)->not->toBeFalse();
+
+    $nextPathStart = strpos($contents, "\n  /", $start + strlen($needle));
+    if ($nextPathStart === false) {
+        $nextPathStart = strlen($contents);
+    }
+
+    $block = substr($contents, $start, $nextPathStart - $start);
+    // Normalise trailing whitespace so the assertion is stable across editors.
+    $normalised = preg_replace('/[ \t]+$/m', '', $block);
+
+    expect($normalised)->toContain("  /modules/stripe/invoice:");
+    expect($normalised)->toContain('summary: Create Stripe invoice (retired - TRU-74 / DRIFT 13)');
+    expect($normalised)->toContain("'410':");
+    expect($normalised)->toContain('stripe_email_payment_disabled');
+    expect($normalised)->toContain('Cancel/clean up a legacy Stripe hosted invoice');
+    expect($normalised)->toContain('cancelLegacyStripeInvoice');
+});