feat: ( payment ) integrate the passenger to payment microservice

packages/types/src/common/payments.ts

@@ -52,6 +52,8 @@ export interface ProviderInitiationInput {
   /** Optional caller-supplied redirect targets for redirect/HPP-style providers. */
   returnUrl?: string;
   redirectUrl?: string;
+  /** Where the browser lands when the hosted page fails/cancels (UX only — never trusted). */
+  failureUrl?: string;
 }
 
 export interface ProviderInitiationResult {
@@ -94,11 +96,6 @@ export enum PaymentReferenceType {
   SHIPMENT = "SHIPMENT",
 }
 
-/** `merchant_order_id` prefix per owning service — lets a webhook be routed before a DB lookup. */
-export const MERCHANT_ORDER_PREFIX: Record<PaymentService, string> = {
-  [PaymentService.PASSENGER]: "PSG-",
-  [PaymentService.FREIGHT]: "FRT-",
-};
 
 /** Body of `POST /payments/initiate` on the payment service (internal, service-authenticated). */
 export interface InitiatePaymentRequest {
@@ -114,6 +111,16 @@ export interface InitiatePaymentRequest {
   provider: ProviderMethod;
   platform?: PaymentPlatform;
   payerAccount?: string;
+  /**
+   * Where the provider's hosted page sends the BROWSER back after success — each calling app
+   * passes its own UI URL (passenger portal vs freight portal). Per-transaction and UX-only:
+   * the redirect never confirms payment (only the webhook / status query does), so per-app
+   * values are safe even though the server-to-server webhook URL is one per merchant.
+   * Falls back to the payment service's provider config when omitted.
+   */
+  returnUrl?: string;
+  /** Failure/cancel counterpart of returnUrl. */
+  failureUrl?: string;
   /** Optional caller key to dedupe retried initiations beyond the per-reference upsert. */
   idempotencyKey?: string;
 }