Merge branch 'staging' into dev-to-staging

packages/types/src/common/payments.ts

@@ -24,6 +24,12 @@ export enum ProviderMethod {
   CARD = "CARD",
   DMONEY = "DMONEY",
   CAC_BANK = "CAC_BANK",
+  /**
+   * CBE Unified Bill Payment — inbound biller integration. We never call CBE: the customer
+   * takes the bill reference to any CBE channel and CBE calls payment-api's /cbe/* endpoints.
+   * No entry in PAYMENT_PROVIDER_MAP by design (docs/cbe/CBE_IMPLEMENTATION_PLAN.md D5).
+   */
+  CBE_BILL = "CBE_BILL",
 }
 
 export type PaymentPlatform = "web" | "mobile";
@@ -40,6 +46,13 @@ export type ClientAction =
       type: "COLLECT_OTP";
       providerOrderId: string;
       message?: string;
+    }
+  | {
+      /** CBE_BILL: show the bill reference the customer pays at any CBE channel. */
+      type: "SHOW_BILL_REFERENCE";
+      billReference: string;
+      instructions?: string;
+      expiresAt?: string;
     };
 
 export interface ProviderInitiationInput {
@@ -130,6 +143,16 @@ export interface InitiatePaymentRequest {
   failureUrl?: string;
   /** Optional caller key to dedupe retried initiations beyond the per-reference upsert. */
   idempotencyKey?: string;
+  /**
+   * Payer full name snapshot (CBE_BILL: fallback for the mandatory Full_Name in /cbe/query
+   * responses when the domain app's bill-query is unreachable).
+   */
+  payerName?: string;
+  /**
+   * Intent expiry, ISO-8601. CBE_BILL: the booking's own payment deadline — NOT a provider
+   * session TTL (the reconciliation sweep cancels the intent when this passes).
+   */
+  expiresAt?: string;
 }
 
 /** Body of `POST /payments/intents/:id/confirm` (OTP-based providers such as CAC Bank). */
@@ -154,6 +177,8 @@ export type PaymentIntentSnapshot ={
   failureCode?: string;
   failureMessage?: string;
   expiresAt?: string;
+  /** CBE_BILL only: the short numeric Bill_Id the customer pays at a CBE channel. */
+  billReference?: string;
   /**
    * Raw provider payload for inspection/debugging — the audit copy of the provider
    * initiation response merged with the latest status-query response (secrets redacted