feat(payment): integrate CAC Bank OTP payments into freight flows

CAC Bank is an OTP debit with no redirect and no webhook: initiate SMSes a
code to the payer's mobile, and the charge only settles when that code is
confirmed. The payment service already spoke it (passenger uses it); the
freight side had the enum values but none of the flow.

API:
- PaymentClientService.confirmOtp forwards the code to
  POST /payments/intents/:id/confirm, mapping 400/404 to BadRequest so a
  mistyped code stays retryable instead of surfacing as a gateway failure.
- PaymentService.confirmOtp is keyed by the LOCAL intent id (the invoice's
  paymentId) rather than the domain reference, so the right invoice settles
  when several share a booking. On success billing settles the invoice.
- payInvoice rejects CAC_BANK without payerAccount before calling the
  gateway, and no longer runs the demo auto-settle for a COLLECT_OTP intent
  (it is not paid until the payer confirms).
- POST /billing/my-invoices/:id/confirm — ownership-checked, and since
  warehouse fee invoices are central invoices it covers those too.

Portal:
- useInvoicePayment owns the whole flow (initiate, redirect-or-OTP, confirm)
  and replaces the five near-identical pay mutations at the call sites.
- PaymentMethodModal gains the CAC Bank option, the payer mobile field, and
  the OTP step. Click-outside is disabled there so a stray click cannot drop
  the payer out of a live OTP window.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

apps/edr-freight-api/src/modules/billing/billing.service.spec.ts

@@ -470,3 +470,78 @@ describe("BillingService.issuePayable", () => {
     expect(manager.update).not.toHaveBeenCalled();
   });
 });
+
+describe("BillingService — CAC Bank (OTP debit)", () => {
+  const openInvoice = {
+    id: "inv-1",
+    status: Freight.InvoiceStatus.Pending,
+    source: Freight.InvoiceSource.Booking,
+    sourceId: "booking-1",
+    type: "PREPAID",
+    invoiceNumber: "INV-20260101-00001",
+    currency: "USD",
+    balanceAmount: 500,
+    totalAmount: 500,
+    paymentId: "intent-1",
+    dueAt: null,
+  };
+
+  const build = (payment: Record<string, unknown>) => {
+    const repo = {
+      findOne: jest.fn().mockResolvedValue(openInvoice),
+      update: jest.fn().mockResolvedValue(undefined),
+    };
+    const service = new BillingService(
+      { getRepository: () => repo } as never,
+      {} as never,
+      {} as never,
+      makeEvents() as never,
+      payment as never,
+      {} as never,
+      {} as never,
+    );
+    return { service, repo };
+  };
+
+  it("rejects a CAC Bank charge with no payer mobile before calling the gateway", async () => {
+    const initiate = jest.fn();
+    const { service } = build({ initiate });
+
+    await expect(
+      service.payInvoice("inv-1", { method: "CAC_BANK" }),
+    ).rejects.toThrow(/payerAccount/);
+    expect(initiate).not.toHaveBeenCalled();
+  });
+
+  it("does not settle an OTP intent at initiate — the payer still has to confirm", async () => {
+    const handlePaymentEvent = jest.fn();
+    const { service } = build({
+      initiate: jest.fn().mockResolvedValue({
+        intentId: "intent-1",
+        immediateSuccess: false,
+        response: {
+          intentId: "intent-1",
+          status: "REQUIRES_ACTION",
+          clientAction: { type: "COLLECT_OTP", providerOrderId: "cac-1" },
+        },
+      }),
+      handlePaymentEvent,
+    });
+
+    await service.payInvoice("inv-1", {
+      method: "CAC_BANK",
+      payerAccount: "77123456",
+    });
+
+    expect(handlePaymentEvent).not.toHaveBeenCalled();
+  });
+
+  it("confirms the OTP against the intent stamped on the invoice", async () => {
+    const confirmOtp = jest.fn().mockResolvedValue({ status: "SUCCEEDED" });
+    const { service } = build({ confirmOtp });
+
+    await service.confirmInvoiceOtp("inv-1", "123456");
+
+    expect(confirmOtp).toHaveBeenCalledWith("intent-1", "123456");
+  });
+});

apps/edr-freight-api/src/modules/billing/billing.service.ts

@@ -12,7 +12,7 @@ import { DataSource, EntityManager, In } from "typeorm";
 
 import { CompaniesService } from "../companies/companies.service";
 import { PaymentService } from "../payment/payment.service";
-import { InitiateResponseDto } from "../payment/payments.dto";
+import { InitiateResponseDto, IntentStatusDto } from "../payment/payments.dto";
 import {
   InvoiceDocumentModel,
   InvoiceDocumentService,
@@ -352,6 +352,34 @@ export class BillingService {
     return this.payInvoice(id, opts);
   }
 
+  /**
+   * Submit the CAC Bank OTP for one of the customer's own invoices
+   * (ownership-checked). Settlement of the invoice happens inside the payment
+   * service when the OTP succeeds.
+   */
+  async confirmInvoiceOtpForUser(
+    id: string,
+    userId: string,
+    otp: string,
+  ): Promise<IntentStatusDto> {
+    await this.findByIdForUser(id, userId);
+    return this.confirmInvoiceOtp(id, otp);
+  }
+
+  /** OTP confirmation by invoice id — the intent is the one stamped at initiate. */
+  async confirmInvoiceOtp(
+    invoiceId: string,
+    otp: string,
+  ): Promise<IntentStatusDto> {
+    const invoice = await this.dataSource
+      .getRepository(Invoice)
+      .findOne({ where: { id: invoiceId } });
+    if (!invoice?.paymentId) {
+      throw new NotFoundException("No payment to confirm for this invoice");
+    }
+    return this.payment.confirmOtp(invoice.paymentId, otp);
+  }
+
   /** Sealed invoice PDF for one of the customer's own invoices (ownership-checked). */
   async documentForUser(
     id: string,
@@ -1035,6 +1063,17 @@ export class BillingService {
       throw new BadRequestException("Invoice has no outstanding balance.");
     }
 
+    // CAC Bank is an OTP debit — the bank SMSes the code to this number, so it is
+    // required up front (the payment service rejects it otherwise, as a 502 here).
+    if (
+      (opts.method ?? "").toUpperCase() === "CAC_BANK" &&
+      !opts.payerAccount?.trim()
+    ) {
+      throw new BadRequestException(
+        "payerAccount (mobile number) is required for CAC Bank",
+      );
+    }
+
     const result = await this.payment.initiate({
       referenceId: invoice.sourceId,
       source: invoice.source,
@@ -1062,7 +1101,12 @@ export class BillingService {
 
     // Settlement is driven by the payment API (webhook/outbox → payment.succeeded);
     // billing must not simulate it. Kept commented for local demos only.
-    if (!result.immediateSuccess) {
+    // An OTP intent (CAC Bank) is NOT paid yet — the payer still has to enter the
+    // code — so the demo shortcut must never fire for it.
+    if (
+      !result.immediateSuccess &&
+      result.response.clientAction?.type !== "COLLECT_OTP"
+    ) {
       await this.payment.handlePaymentEvent({
         eventType: "payment.succeeded",
         eventId: `demo-${result.intentId}`,

apps/edr-freight-api/src/modules/billing/dto/pay-invoice.dto.ts

@@ -1,5 +1,13 @@
-import { ApiPropertyOptional } from "@nestjs/swagger";
-import { IsIn, IsOptional, IsString } from "class-validator";
+import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
+import { IsIn, IsNotEmpty, IsOptional, IsString } from "class-validator";
+
+/** OTP submitted for a COLLECT_OTP provider (CAC Bank). */
+export class ConfirmOtpDto {
+  @ApiProperty({ description: "One-time password SMSed by the bank." })
+  @IsString()
+  @IsNotEmpty()
+  otp!: string;
+}
 
 /** Gateway options for paying an invoice from the customer portal. */
 export class PayInvoiceDto {

apps/edr-freight-api/src/modules/billing/portal-billing.controller.ts

@@ -18,7 +18,7 @@ import {
 } from "../../common/resolve-auth-user-id";
 import { sendPdf } from "./billing.controller";
 import { BillingService } from "./billing.service";
-import { PayInvoiceDto } from "./dto/pay-invoice.dto";
+import { ConfirmOtpDto, PayInvoiceDto } from "./dto/pay-invoice.dto";
 
 /**
  * Customer-facing billing endpoints. Unlike {@link BillingController} (admin,
@@ -96,4 +96,20 @@ export class PortalBillingController {
       failureUrl: dto.failureUrl,
     });
   }
+
+  @Post("my-invoices/:id/confirm")
+  @ApiOperation({
+    summary: "Confirm an OTP-debit payment (CAC Bank) for one of the customer's invoices",
+  })
+  confirmOtp(
+    @Param("id", ParseUUIDPipe) id: string,
+    @CurrentUser() user: AuthUserPayload,
+    @Body() dto: ConfirmOtpDto,
+  ) {
+    return this.billingService.confirmInvoiceOtpForUser(
+      id,
+      resolveAuthUserId(user),
+      dto.otp,
+    );
+  }
 }